kamo
/
tag
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

04 tree

Browse Source
main
km0 1 year ago
parent 81d50ec1a7
commit fb5e75eea8
2 changed files with 110 additions and 13 deletions
Show Stats Download Patch File Download Diff File

50
03/index.html
Unescape Escape View File

@ -10,34 +10,58 @@
<h1>doc doc doc</h1>
<div class="sub">documenting code documentation</div>
<div class="info">hello! welcome. this is an archive to navigate trough documentation practices</div>
<div class="attempt">pair programming and pair reading.</div>
<div class="attempt">pair programming and pair documenting</div>
</header>
<section>
<div class="prompt">
<p>
The practice of pair programming involves two developers coding together on the same machine, with distinct roles. The <em>driver</em> writes the actual code, while the <em>navigator</em> reviews each entry along the way.
Roles are often switched.
Developers with similar or different experience can collaborate in pair programming, with benefits for both parts.
</p>
<p>
The practice of pair programming involves two developers coding together on the same machine, with distinct roles. The <em>driver</em> writes the actual code, while the <em>navigator</em> reviews each entry along the way.
Roles are often switched.
Developers with similar or different experience can collaborate in pair programming, with benefits for both parts.
</p>
<p>
Could the concept of pair programming be applied to documentation?
</p>
<p>
Navigating through documentation can be difficult.
Could the concept of pair programming be applied to documentation?
</p>
<p>pair documentation writing: one writes and the other provides perspective, such as reviewing if there are parts that are not clear</p>
<p>pair documentation reading: one read and the other ??? </p>
<p>pair documentation writing: one writes and the other provides perspective, such as reviewing if there are parts that are not clear</p>
<p>pair documentation reading: one read and the other ??? </p>
<p>experiments with pair doc writing together with chae for the <a href="https://git.xpub.nl/manetta/flask-example/src/branch/documentation">flask example repo</a>, that led to a more welcoming and vernacular way of writing</p>
<p>experiments with pair doc writing together with chae for the <a href="https://git.xpub.nl/manetta/flask-example/src/branch/documentation">flask example repo</a>, that led to a more welcoming and vernacular way of writing</p>
<p>what could it mean to read documentation in pair?</p>
<p>what could it mean to read documentation in pair?</p>
</div>
<div class="prompt">
<p>Documentation is not just for beginners, is a code companion. One never stops reading. Both newcommers and experienced developers alike read documentation, that meets them in different moment of their programmer lives, from the <em>hello world</em> to the <em>how to uninstall</em></p>
<p>when pairing reading make sense? which kind of situations?</p>
<p>im struggling because all of these things are activities and not objects and this cause me disconfort </p>
<ul class="props">
<li>one read, the other document the reading process: keeping track of the screen walk, annotating resources, drating a map of where knowledge has been found</li>
</ul>
</div>
</section>
</body>
</html>

73
04/index.html
Unescape Escape View File

@ -0,0 +1,73 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>04 - Tree</title>
<link rel="stylesheet" href="/style.css">
</head>
<body>
<header>
<h1>doc doc doc</h1>
<div class="sub">documenting code documentation</div>
<div class="info">
hello! welcome. this is an archive to navigate trough documentation practices
</div>
<div class="attempt">
<p>
The path through documentation resources in the making of a project could be represented as a tree structure, where the root is the project idea or need and then branches all the explored direction and lateral resources.
</p>
<p>
Tree structures recall hierarchy, because of the different structural positions of branches and leaves. However what I'm interested here is the temporality of the tree. There is a starting point, a root, and then different tryouts, with dead ends, ramifications, different experiments.
</p>
<p>
An example is <a href="https://github.com/mbbill/undotree">undo-tree</a> where instead of the linear approach of <code>ctrl-z</code>, a fluorishing history of attempts is preserved.
</p>
</div>
</header>
<section>
<p>
So the plan is: keep track of your path. Start from something (could be an idea for a project, a need for understanding, the writing of some documentation) and then keep track of the various resources encountered through time in a tree-like structure.
</p>
<p>
This excercise seems flexible enough to host different approaches and materials. Could be an history of navigation through hyperlinks, but also contain reflections and snapshots of how the initial idea changes during time. Ideally every node of the tree could be a potential entry point / backdoor to reflect on documenting practices.
</p>
<p>
It could be tried in alone or in group, with one or many trees. To have a less linear and more entangled structure. It could host practices such as the one of <em>03 - Pair</em>, where one driver go through and the navigator map into the tree.
</p>
</section>
<ul class="questions">
<li>how to think about the tree as a writing machine?</li>
<li>how to store information in a way that is not too intrusive for the process?</li>
<li>how to represent the tree?</li>
</ul>
<section>
<h2>Prototype
</h2>
<div class="root">
<h3>
Comparative Iceberg Studies
</h3>
<p>
Write a image scraper to download a bunch of picture from the iceberg meme template (that maps facts about a topic from the tip, common knowledge, to the bottom, esoteric, misterious, unknown details). Group the image and align all of them. Call people within the field of each topic and make them comment the result. Edit and bound.
</p>
</div>
</section>
</body>
</html>
Write Preview
Loading…
Cancel
Save