HackMD
Notes Lab Notebooks and Architecture Design Records
- I think everyone agrees: we should make this a key part of our culture.
- "Thinking in the Open" is a huge productivity booster.
- etc
Challenges are:
- encouraging and enculturalizing this
- organizing the results (or at least making them discoverable)
This is probably subtle:
- too much organization is a barrier to creation
- too much "discoverability" may result in channels with bad noise/signal ratio
- not enough discoverability and it's not accomplishing "thinking in the open"
There may also be different kinds of documents we should consider.
Drafting vs refining vs finalizing can all benefit from different flows.
Notes on Attempts and Outcomes
There are many possible ways (both in techniques and platforms and formats)
to try to form repositories of knowledge like this.
We may want to pick several to encourage – different formats and techniques
might be better suited for documents at various levels of production.
exploration reports
We tried a concept I dubbed "exploration reports" in IPLD. It sort of worked.
-
the stuff:
- a directory of them: https://github.com/ipld/specs/tree/master/design/history/exploration-reports
- more readmes about the concept: https://github.com/ipld/specs/blob/master/design/history/README.md and https://github.com/ipld/specs/blob/master/design/history/FAQ.md
-
my thoughts after trying this for a while:
- definitely the right direction. (maybe not the perfect heading or magnitude, but the right general direction.)
- team agrees, periodically comments on them as having been constructive.
- failing? we still don't use them enough. (team comments also tend to say this at the same time as saying they've been constructive.) so why is this? what lessons can we learn?
- Friction still too high. Github PR UX is absolutely disastrous for this – invites argument. Purpose of these is low-friction notes without argument. It's critical to have some space to write and share writing that is aimed at sharing without demanding resolution; github absolutely awful at encouraging that, even if you try to explicitly communicate policies and intentions about this. (Maybe scripting of some kind would help?)
- People resist sharing incomplete stuff. (Different mediums seem to have this at different rates. Github induces high resistance to incomplete sharing compared to ex. hackmd.)
- one positive thing to note about collating everything into files on github: can grep them. I use this on a regular basis to find notes about topics.
gists (for drafts)
- work pretty well for me. examples:
- appears to induce less resistance to incomplete sharing; good. (slightly; possibly for some people and not others. unclear.)
- linkable, and lends itself very very well to "point in time" documents, which is a good property for for referencable ADRs.
- UX of gists clearly communicates that this is single-author and not resolution-bound, which is extremely extremely good.
- unfortunately large hurdle to later move content from these to github PRs when time to make a more canonical document. (Not necessarily a problem, though. The draft can just be reference material.)
hackmd (for collaborative editing)
- examples:
- … this!
- has concurrent cursors for all users, comment systems, etc.
- bad place for permanent reference. good place for inviting people to collaborate on something.
- comparable to cryptpad. i just like hackmd a lot better.
- also comparable to google docs, arguably, but since hackmd does markdown, it's ready to paste content into gists or files on github, which is helpful.
github issues (for… arguing?)
- github issues are an obvious place to consider dumping knowledge, since we do a lot of work on github already.
- they're really problematic. A linear flow of conversation is generally Not Good. It does not naturally trend itself towards refinemnt. Issues over a certain length of discussion become unnavigable.
- one positive of this platform: it's very easy to ask our community to engage and comment on these.
- discoverability of github issues is… a known problem.
- always a conflict of interest between {issues are for project tracking} and {issues are for discussion}.
- a good workflow seems to be: opening discussion issues specifically to recruit feedback and not to decide or refine… and after some predetermined input period, say thanks, close it, and start lifting the most constructive results to another medium to continue.
- in general: the negative aspects of github issues are managable with culture and process. It just takes a lot of both.
mural (for brainstorming)
- Mural provides a two-dimensional and visual interface rather than a linear textual one which can be very useful for brainstorming
- also provides a zoom-out overview… which shows rectangles for where various user's viewport is at. Very useful for coordinating discussion.
- less great for after-brainstorming. can export pdfs but others not particular convenient to paste content out to elsewhere.
- also, nonfree.
Format-Agnostic Observations
- regardless of the format and host of the documents, mandating filenames starting with
YYYY.MMhas been a good idea: it clearly centers the point that these documents are point-in-time snapshots of considerations that were weighed at that time… and leaves space for new documents to be written without resolving conflicts, which results in more net records produced. For anything other than the absolutely final resolved documents, this is a net win. - overall seems like these experiences strongly indicate that an indexing convention that can tolerate documents in all sorts of repositories and formats is highly desirable.
- may simultaneously still be useful to have a single github repo with a folder that's a "default" location. Slightly more communicable: easier to point people at this and say "do your work here" than to say "do your work {somewhere}" because of the slightly more guidance and context offered by the suggestion of this folder.
live notes (chatting: warpfork, iand)
-
encourage: small glossaries, in documents! don't rely on ambient information flow for key words!
- we're inventing concepts and naming them all the time. this is akey part of the process, not incidental.
- especially critical if we're using the same terms in multiple varied proposals for the same domain.
-
encourage: list constraints and forces on the design, at the top. this deserves a section itself!
- "setting the scene"
- you want to be able to get people involved who aren't already intimately familiar
- "setting the scene"
-
not all projects need to "write specs", there are various kinds of documents
- example: sentinel project:
- doesn't really need to write "specs" right now
- does consume specs (from filecoin, for data structures especially)
- in the future if the project builds new query systems, those would probably need something more spec-like to develop
- does need design docs and architecture design records
- example: sentinel project:
-
we should make some templates for design docs
- should give suggestions, but not be a format straightjacket.
- example user story: if someone gives you a doc that you can't make sense of: should be able to link them to the skeleton and say "could you consider formatting it like this?"
-
getting early feedback is critical to design our processes for
- different documents may aim for different stages of completeness
- and different size of audience
- documents that get too complex become unapproachable and cannot get good feedback
- if you need to include lots of details: maybe put them into "appendix" sections
- documents that take too long to prepare (because they're too formal, or too complex, etc) obviously can't get early feedback
- different documents may aim for different stages of completeness
-
"the function of a design doc is scalability of communication": "it should be consumable asynchronously".
-
consider: if you're going to write an early design document: can you think of who you'll want early review from?
- let these people know
- when you launch the document, consider scheduling a meeting in the next week to give a deadline for review and discussion.
- consider saying: "this is now open for discussion; if there is no feedback, i'll be executing on this plan starting {date}."
-
joy of exploration reports: reporting your dead ends.
- lots of things get too open-ended, or run out of time, or there's enough time to also consider alternatives, etc. outcomes from these to keep someone from going to same way is good.
- fun anecdote: if you're doing genelogical research – looking for records hundreds of years old – you need to record the failed results! Otherwise you'll end up re-attempting the same search a year later.
- lots of things get too open-ended, or run out of time, or there's enough time to also consider alternatives, etc. outcomes from these to keep someone from going to same way is good.
-
should we have a short meta-doc that recommends feedback scopes?
- e.g.:
- share with a specific colleague that's most relevant
- share with your team or other small channel
- share with #engineering for general interest
- e.g.:
-
facets of this problem:
- what place/format/host/platform should these docs take?
- how many different kinds of docs are there (e.g. that we could make distinctive skeletons for)?
- one draft of maybe the categories:
- exploration reports: can explore only one thing
- architecture design records: really ought to list alternatives (or if not: why you didn't consider any!)
- design docs: a full plan for implementing a particular approach (ADRs might include several very small forms of these)
- docs: the updated, unified source of truth about what is (doesn't need to spend as much time on alternatives).
- one draft of maybe the categories:
- how do we maintain things up to date – or, alternatively – connect generational documents, discoverably?
- how do we detect failure to keep things up to date?
- consider the joy of footnotes: total document updates can be disconcerting; footnotes can be more useful.
-
maybe a goal:
- gather a list of example document links… and we will extract good features from these
- put a call out in #engineering for inputs?
- gather a list of example document links… and we will extract good features from these
-
interesting to note: "transparency trap":
- e.g., in our organization we notice that a team that has 10 people on it often has 30 to 50 people in its slack channel.
- this means we don't actually have small-group venues (e.g. for share radius "2" by the above idea).
- problematic! may cause people to push their documents to other even-more insular places (slack group-DMs? farther afield places? etc).
