Writing documentation for your team - Deepstash

Keep reading for FREE

Document the right things

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

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

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

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

CURATED BY

tuantm

just geek

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.

stash-superman-illustration

Explore the World’s

Best Ideas

200,000+ ideas on pretty much any topic. Created by the smartest people around & well-organized so you can explore at will.

An Idea for Everything

Explore the biggest library of insights. And we've infused it with powerful filtering tools so you can easily find what you need.

Knowledge Library

Powerful Saving & Organizational Tools

Save ideas for later reading, for personalized stashes, or for remembering it later.

# Personal Growth

Take Your Ideas

Anywhere

Organize your ideas & listen on the go. And with Pro, there are no limits.

Listen on the go

Just press play and we take care of the words.

Never worry about spotty connections

No Internet access? No problem. Within the mobile app, all your ideas are available, even when offline.

Get Organized with Stashes

Ideas for your next work project? Quotes that inspire you? Put them in the right place so you never lose them.

Join

2 Million Stashers

4.8

5,740 Reviews

App Store

4.7

72,690 Reviews

Google Play

Shankul Varada

Best app ever! You heard it right. This app has helped me get back on my quest to get things done while equipping myself with knowledge everyday.

Sean Green

Great interesting short snippets of informative articles. Highly recommended to anyone who loves information and lacks patience.

samz905

Don’t look further if you love learning new things. A refreshing concept that provides quick ideas for busy thought leaders.

Ashley Anthony

This app is LOADED with RELEVANT, HELPFUL, AND EDUCATIONAL material. It is creatively intellectual, yet minimal enough to not overstimulate and create a learning block. I am exceptionally impressed with this app!

Giovanna Scalzone

Brilliant. It feels fresh and encouraging. So many interesting pieces of information that are just enough to absorb and apply. So happy I found this.

Jamyson Haug

Great for quick bits of information and interesting ideas around whatever topics you are interested in. Visually, it looks great as well.

Ghazala Begum

Even five minutes a day will improve your thinking. I've come across new ideas and learnt to improve existing ways to become more motivated, confident and happier.

Laetitia Berton

I have only been using it for a few days now, but I have found answers to questions I had never consciously formulated, or to problems I face everyday at work or at home. I wish I had found this earlier, highly recommended!

Read & Learn

20x Faster

without
deepstash

with
deepstash

with

deepstash

Access to 200,000+ ideas

Access to the mobile app

Unlimited idea saving & library

Unlimited history

Unlimited listening to ideas

Downloading & offline access

Personalized recommendations

Supercharge your mind with one idea per day

Enter your email and spend 1 minute every day to learn something new.

Email

I agree to receive email updates