Twitter | Search | |
This is the legacy version of twitter.com. We will be shutting it down on 15 December 2020. Please switch to a supported browser or device. You can see a list of supported browsers in our Help Center.
Lev Walkin
One like — one non-trivial tip about making quality engineering documentation. Go.
Reply Retweet Like More
Lev Walkin Nov 13
Replying to @levwalkin
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.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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:
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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!
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
6. No one reads documentation.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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).
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
20. The document is never a goal. Fight me.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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?
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
22. There are techniques for tracking requirements. E.g., assign hashtags to them: • We should not fail. • We should be fast. “Alternative 1 covers but doesn’t address ”.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
27. Optimize for panicked engineer’s doomscrolling.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
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.
Reply Retweet Like
Lev Walkin Nov 13
Replying to @levwalkin
Crap, I am out of steam. Stop liking.
Reply Retweet Like