Explore the World's Best Ideas
Join today and uncover 100+ curated journeys from 50+ topics. Unlock access to our mobile app with extensive features.
Document the right things
"Be selective about what you document and what you don't."
"Documenting everything leads to noise that is a burden to maintain over time"
Whether something is worth documenting or not (why something is worth documenting):
- What common questions do you spend a lot of your time answering (in active context)?
- What information is poorly understood by your team?
- What information is neccessary for people to make informed decisions?
"Documentation isn't free; you bear a one-time cost for writing it and a recurring cosst for maintaining it forever."
7
65 reads
Understand the audience
Understanding the reader of your writing documentation:
- What does the reader bring to the table? What context do they have that equips them to understand the context?
- Why is the reader reading your documnetation? What problems are they trying to solve?
Identify the target audience at the beginning of your documentation so readers can confirm reading it is worth their time (also remind the required knowledge and share links to introductory resources or summary that).
New terms should be emphasized (bold) with description in footer or appedix.
"Bias towards simple over clever"
6
47 reads
Layer your communication
"Structure your documentation to accomodate the different levels of investment with which readers will approach it"
Each readers has their own ways to read your document (from beginning to end, skimming and dive deeper into the interesting section ...), organize your document will help them:
- Use headings and subheadings liberally
- Add TOC to orient the reader with hyperlink for sections of the document (whenever possible)
- Keep paragraphs short; avoid "wall of text"
6
40 reads
Consider the future
"Implement practices that help your documentation age well over time"
- Be concise. Don't repeat yourself. Maintainers should have to update the same information in as few places as possible.
- Explain why things are the way they are - help future readers decide for themselves what is still true instead of trusting your bygone context.
- Link to "sources of truth" liberally (also with references) - help maintainer update after the source changes.
- Add created time for your document.
- Collective ownership (team) over all documentation.
- Recognize contributions.
- Encourage readers to feedback.
6
39 reads
IDEAS CURATED BY
CURATOR'S NOTE
Good documentation is essential to teams' productivity. It's hard to write documentation that is relevant, accessible and ages well over time. Everything changes time by time. Maintaince of documentation is essential to keep it fresh.
“
Other curated ideas on this topic:
5 ideas
10 ideas
Best practices for writing code comments
stackoverflow.blog
13 ideas
The Art of Technical Writing | WorksHub
works-hub.com
Read & Learn
20x Faster
without
deepstash
with
deepstash
with
deepstash
Personalized microlearning
—
100+ Learning Journeys
—
Access to 200,000+ ideas
—
Access to the mobile app
—
Unlimited idea saving
—
—
Unlimited history
—
—
Unlimited listening to ideas
—
—
Downloading & offline access
—
—
Supercharge your mind with one idea per day
Enter your email and spend 1 minute every day to learn something new.
I agree to receive email updates