Compare commits
3 Commits
fe4621281c
...
fb5e75eea8
| Author | SHA1 | Date |
|---|---|---|
 km0
|
fb5e75eea8 | 1 year ago |
|
km0
|
81d50ec1a7 | 1 year ago |
|
km0
|
be72324af3 | 1 year ago |
@ -0,0 +1,67 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>03 - Pair</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">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>
|
||||
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>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>
|
||||
|
||||
</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>
|
||||
@ -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>
|
||||
Loading…
Reference in New Issue