One like — one non-trivial tip about making quality engineering documentation. Go.
1. Value-producing systems are set up to benefit from explicit feedback loops.
[e.g. peer review, CI/CD, QA are parts of feedback loops for making quality software.]
Documentation is a process teams frequently overlook to organize feedback loops for.
[e.g. peer review, CI/CD, QA are parts of feedback loops for making quality software.]
Documentation is a process teams frequently overlook to organize feedback loops for.
2. As a ton of code doesn’t mean quality, experts call for a very light _amount_ of documentation. Otherwise the information overload and ongoing maintenance bring the costs up and usefulness down. “Just enough”, they say.
Andreas Rüping provides a scientific diagram:
Andreas Rüping provides a scientific diagram:
3. Organizing process explicitly around lightweight feedback loops can bring the documentation quality up, and costs down. Who cares that is also can helo building better products by fostering better long-term decision-making. Oh, right, we do!
4. Example small feeback loop around documentation artifacts:
• Produce [a skeleton of] a document as part of a decision-making meeting.
• Ask a colleague to co-write the document with you.
• Ask a member of the intended audience to review your document.
• Produce [a skeleton of] a document as part of a decision-making meeting.
• Ask a colleague to co-write the document with you.
• Ask a member of the intended audience to review your document.
5. Example large feedback loops:
• Ask engineers to maintain a document lifecycle, which includes seeking explicit feedback from others as a checkmark.
• Organize [recurring] meetings where colleagues can complain about their problems with the existing body of documentation.
• Ask engineers to maintain a document lifecycle, which includes seeking explicit feedback from others as a checkmark.
• Organize [recurring] meetings where colleagues can complain about their problems with the existing body of documentation.
6. No one reads documentation.
7. Keep the audience in mind. Nobody does that, you should.
Keep the audience small and personified. Write for Julia from this team, or Jeff from that team. If documenting an API, know the name of the user.
Keeping a person in mind makes a document clear, concise and punchy.
Keep the audience small and personified. Write for Julia from this team, or Jeff from that team. If documenting an API, know the name of the user.
Keeping a person in mind makes a document clear, concise and punchy.
8. Really, nobody reads documentation. And it is not just because it is generally badly written (due to lack of artifact feedback) and frequently obsolete (due to lack of process feedback).
9. Document co-editing may be used to create value by:
• Supporting better exploration of the problem and solution spaces.
• Fix discrepancies in understanding. Making sure everyone is on the same page.
There are techniques to support that.
• Supporting better exploration of the problem and solution spaces.
• Fix discrepancies in understanding. Making sure everyone is on the same page.
There are techniques to support that.
10. For problem space exploration, do not start by forcing a particular logical organization. Keep it free-flowing. If the structure emerges, capture it by using the hierarchical headers and other formatting tools. Go over the document and add possibly required elements later.
11. The document has a goal. It would help to understand it clearly. You can start with it, or end weiting with it. Make sure the document reaches the goal at the end of the process.
The goal of the proposal is different from the goal of the proposed.
The goal of the proposal is different from the goal of the proposed.
12. People do not read documents, they consume them by scanning.
A person seeking help:
• scans existing documents’ titles,
• asks a colleague in chat,
• skims through two random docs.
• complains on Twitter and Zooms a colleague,
• takes the first SO answer.
Nobody reads.
A person seeking help:
• scans existing documents’ titles,
• asks a colleague in chat,
• skims through two random docs.
• complains on Twitter and Zooms a colleague,
• takes the first SO answer.
Nobody reads.
13. To increase utility, optimize for scanning.
• Use two levels of hierarchy.
• Use lists.
• Use tables.
• Use diagrams.
• Use code snippets.
• Split into subdocuments and provide two-way links.
Do not make people read paragraphs to find answers in the middle of them.
• Use two levels of hierarchy.
• Use lists.
• Use tables.
• Use diagrams.
• Use code snippets.
• Split into subdocuments and provide two-way links.
Do not make people read paragraphs to find answers in the middle of them.
14. A trick for better decision making is to explicitly list the “business need”.
Business need in a corp can be a highest level value your team provides to other teams.
Business need is higher than a business requirement.
Verify the design addresses the busines need.
Business need in a corp can be a highest level value your team provides to other teams.
Business need is higher than a business requirement.
Verify the design addresses the busines need.
15. For more complex systems, separating the business needs from business requirements from technical requirements and further allows:
• Independent validation of proposed design.
• Re-engineering the solution if need arises, with no fear of missing important requirements.
• Independent validation of proposed design.
• Re-engineering the solution if need arises, with no fear of missing important requirements.
16. Extreme Programming popularized pair programming. I hate it, for a number of reasons. I get overwhelmed by others and can’t think; I need quiet.
I love pair documentation and co-editing. If nothing else, it allows broadly enumerating things for deeper analysis later.
I love pair documentation and co-editing. If nothing else, it allows broadly enumerating things for deeper analysis later.
17. It helps to optimize scanning for relevancy, makes it faster to skip docs.
• List involved ppl, starting with the author maintaining a doc, reviewers.
• Add a label that tells which point on the lifecycle document is on: draft, ratified, obsolete, etc. Maintain it.
• List involved ppl, starting with the author maintaining a doc, reviewers.
• Add a label that tells which point on the lifecycle document is on: draft, ratified, obsolete, etc. Maintain it.
18. There’s a concept of information foraging: people would only read if they can justify spending cognitive energy.
Make your docs a higher calorie food: less background text, more points and solutions. Use working examples to provide most calories.
Make your docs a higher calorie food: less background text, more points and solutions. Use working examples to provide most calories.
19. If you don’t know why are you writing the doc, don’t.
No clear goal or very wide audience? Don’t!
Improve the product or automate the problem away instead.
This is my Zero Documentation principle.
No clear goal or very wide audience? Don’t!
Improve the product or automate the problem away instead.
This is my Zero Documentation principle.
20. The document is never a goal. Fight me.
21. There are techniques for better decision-making using [pair-]documentation.
• List alternatives. Analyze their pro’s and cons’ against stated requirements.
• List the business need and reqs and ask “can I _remove_ something to address it”?
• Can I make it even simpler?
• List alternatives. Analyze their pro’s and cons’ against stated requirements.
• List the business need and reqs and ask “can I _remove_ something to address it”?
• Can I make it even simpler?
22. There are techniques for tracking requirements. E.g., assign hashtags to them:
• #NOFL We should not fail.
• #SPD We should be fast.
“Alternative 1 covers #NOFL but doesn’t address #SPD”.
• #NOFL We should not fail.
• #SPD We should be fast.
“Alternative 1 covers #NOFL but doesn’t address #SPD”.
23. Allow wide(r) range of people to comment on and modify your shared docs.
If someone asks “is it still relevant?”, delete the document, yagni.
If this scares you, just leave a bold red note in the beginning “// OBSOLETE”, or maybe just edit it to restore relevancy.
If someone asks “is it still relevant?”, delete the document, yagni.
If this scares you, just leave a bold red note in the beginning “// OBSOLETE”, or maybe just edit it to restore relevancy.
24. Two-way linking. When you refer to something (code?) from the document, consider referring back to the document’s URL from there. And vice versa.
Xanadu style.
Xanadu style.
25. To support the team in maintaining the quality feedback loops, consider incentives.
• Short term: “like” each other’s docs.
• Med term: doc leaderboards in some systems (Confluence). I am ambivalent tho.
• Long term: as a manager, include “I like your docs” in reviews.
• Short term: “like” each other’s docs.
• Med term: doc leaderboards in some systems (Confluence). I am ambivalent tho.
• Long term: as a manager, include “I like your docs” in reviews.
26. Have a periodic reminder to go over the body of documents and perform maintenance. Moving around to maintain structure, marking docs obsolete. Like a FlyLady — the objective is not to be “done”, but to spend 5 minutes a month to do whatever you can.
27. Optimize for panicked engineer’s doomscrolling.
https://twitter.com/copyconstruct/status/1327475813554372608
28. Do not require a document for every $concept (feature, component, product). This produces noise.
Do not write if you can’t name a person who needs it and asks for it and eagerly awaits to review it. Co-author with them.
Sometimes the person is just you, that’s ok.
#ZeroDoc
Do not write if you can’t name a person who needs it and asks for it and eagerly awaits to review it. Co-author with them.
Sometimes the person is just you, that’s ok.
#ZeroDoc
Crap, I am out of steam. Stop liking.
• • •
Missing some Tweet in this thread? You can try to
force a refresh
