Tip 50 - tip your server
Use tips for actionable, optional, been-there-done-that content.
50 tips in 50 days
51 posts with the tag “50 tips in 50 days”
Tip 49 - NWTWWHB
What doesn’t kill you makes (your docs) stronger.
Tip 48 - do it yourself
Use examples to enhance your point, not make it.
Tip 47 - Ch-ch-ch-ch-changes
Document change like a verb, not just as a noun.
Tip 46 - it's not a bug; it's a feature!
Emphasize the positive! Help your readers achieve, not avoid.
Tip 45 - and another thing...
Every new fact is ‘another thing’, but you don’t always need to call attention to it!
Tip 44 - we did it!
Separate yourself from, and instead focus on, your reader.
Tip 43 - what's in a name?
Sneak in “extra docs” with meaningful example file names.
Tip 42 - knock knock, who's there?
Assume that your reader knows whose docs they’re reading.
Tip 41 - if you please
Docs is not a conversation. Skip the pleasantries!
Tip 40 - make my day
“Make things happen” in your life, not in your docs writing.
Tip 39 - smarty pants
Don’t sound smart; make your reader feel smart!
Tip 38 - this and that
Save “but” for a truly unexpected turn of events. You can use “and” more than you think!
Tip 37 - right words, wrong place
You may need to ‘rearrange’ to support your reader’s journey, not rewrite.
Tip 36 - not my problem
Don’t take responsibility for documenting someone else’s project.
Tip 35 - link in bio
Links are going to be clicked! Use them strategically when you want readers to leave your page.
Tip 34 - show what to do
Show the right thing so readers don’t internalize the wrong thing.
Tip 33 - what's your problem?
Start troubleshooting advice with the observable error, not what led to it.
Tip 32 - defining the obvious
The better the name, the harder you have to work for the definition.
Tip 31 - as not shown here
Don’t explain what’s not in the example.
Tip 30 - just a link in your chain
When your users have users, you may want or need to document for them, too.
Tip 29 - seen and not heard
Use visual emphasis for conveying meaning, not intonation.
Tip 28 - this time
Acknowledge the similarities to and differences from earlier instructions.
Tip 27- writing that clicks
Focus on your reader’s needs, not their mechanics.
Tip 26 - use this
Use the words you mean.
Tip 25 - just follow this one simple tip
Your enthusiasm isn’t always contagious.
Tip 24 - mise en place
Front load prerequisites to avoid distracting side quests.
Tip 23 - is not was
Write the docs you have, not how you got them.
Tip 22 - and then
Start with one idea per sentence. Let it tell you whether it wants to be longer or shorter.
Tip 21 - prepare to be assimilated
Consider the surrounding context around your changes.
Tip 20 - add this code
Make sure readers can actually add your “add this code” examples.
Tip 19 - be the change you want to see
When communicating updates to your project, emphasize what has changed for the reader.
Tip 18 - twist *then* pull
Use sequence words to help your reader progress through your instructions.
Tip 17 - go with the flow
Group the most similar items together for a definition that flows.
Tip 16 - read this tip... if you want to
You don’t know what your reader wants. Save effort (and words!) by not trying to guess.
Tip 15 - don't doc when you can fix
Don’t document workarounds. Fix them!
Tip 14 - this post includes advice
Make it clear whether your list is partial or complete.
Tip 13 - inadvertently inappropriate
Be aware of words that may have an unintended nuance.
Tip 12 - cool story bro
Let your docs tell their own story.
Tip 11 - don't regret what could have been
Alternative versions are more helpful than alternate histories.
Tip 10 - headings need to work alone
Consider everywhere your headings will be used, not just in the body of the page.
Tip 9 - I dislike "like"
Don’t make people figure out how one thing is ‘like’ something else.
Tip 8 - don't forget
You can’t remember (or forget) what you didn’t already know.
Tip 7 - title your code blocks
Add file names as titles to your code blocks.
Tip 6 - new gets old fast
New gets old fast. Save it for timely or dated posts.
Tip 5 - don't let the easy edit distract you
Don’t let the easy fix distract you from the better edit.
Tip 4 - make headings
When you think (or realize) you’ll reference something frequently, make it a heading.
Tip 3 - repetition is a pedagogical tool
Repetition is a pedagogical tool to reinforce a concept, not a safety net.
Tip 2 - put the condition first
When an instruction is conditional, put the condition before the action to perform.
Tip 1 - "... if one does not already exist"
When instructing a reader to make a new file or folder, acknowledge that one might already exist.
50 Docs tips in 50 days
It’s 50 days until I turn 50! So I thought I’d celebrate with a different docs tip every day.
Toggle Comments
© 2021 - 2024 Sarah Rainsberger. Except where otherwise noted, and/or quoting external sources, the content of this site is licensed under CC BY-NC-SA 4.0 
