Writing Reasonable Documentation
I find it strange that most people seem to be rather horrible at writing documentation. While this is simply a subjective opinion of mine (who am I to say that I am any better than they), it is one that many of my colleagues share.
Writing documentation, once you're in the mood for it, is quite easy. You simply explain how to understand/use a piece of software in a concise, mildly entertaining fashion.
- Don't explain everything - leave some mystery.
- Explain what needs to be explained, and get on with it.
- Show some examples.
- Expect people to skip over most large blocks of text, so avoid them entirely.
Ideally, the software does a good job of explaining itself. If not, you may want to consider a new approach to your design (or accept the complications of your codebase's territory).
That's the best advice I can give to anyone trying to write better documentation (if they consider mine to be of any merit, that is).
Thoughts & Musings: a (Public) Journal
A collection of hand-written essays by Kenneth Reitz.
- My Last Manic Episode.
- The Secret to My Success: Stimulants.
- My Favorite Python Libraries.
- Competition and Open Source.
- On Polyamory.
- Feeling Better & Reflecting on Open Source.
- A Good Hat.
- Dinner with a Narcissist.
- Working from Home — a Double-Edged Sword.
- Truest Love.
- Writing Reasonable Documentation.
- On Traveling and Depression.
- Pipe Dream: Making a Game.
- On Depression, Part I (of many).
- I Do Lots of Things.
- On Conferences and Travel.
- On Psychedelics and Other Drugs.
- On Irritability in Open Source.
- Attempting to Reduce Stimulants Usage.
- On Depression, Part II.
- The Far Side of Madness.
- A Concise List of Personal Values.
- Why This isn't a Blog.
- Back to Work.
- Stuck in a Rut.
- New Project Idea: Environment Variables.
- Esoteric Interest and Current Bookshelf.
- It's About Time....
- On Inspiration and Tools (like languages).
- Positivity, Coming Soon™.
- The Anxiety of Clout.
- Living With Reasonable Regrets.
- Soul Purpose.
- On Open Source and Impactfulness.
- Fellowship at PyCon (upcomming).
- Sharing is Therapeutic.
- Seeking Inspiration, Somewhere.
- First Entry.
- Three Concise Truths.
- iPad as a Main Computer.
- On Writing Music and Emotional Landscape.
- Self Therapy or Professional & Amphetamines.
- On Writing.
- Switching Cameras (again).