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.
- A Letter to /r/python.
- My Last Manic Episode.
- The Secret to My Success: Stimulants.
- On Polyamory.
- My Favorite Python Libraries.
- Dinner with a Narcissist.
- Competition and Open Source.
- I Do Lots of Things.
- A Good Hat.
- Working from Home — a Double-Edged Sword.
- iPad as a Main Computer.
- Truest Love.
- Feeling Better & Reflecting on Open Source.
- On Depression, Part I (of many).
- Writing Reasonable Documentation.
- On Psychedelics and Other Drugs.
- On Traveling and Depression.
- Pipe Dream: Making a Game.
- On Depression, Part II.
- A Concise List of Personal Values.
- On Irritability in Open Source.
- Why This isn't a Blog.
- Attempting to Reduce Stimulants Usage.
- The Far Side of Madness.
- On Conferences and Travel.
- Esoteric Interest and Current Bookshelf.
- Back to Work.
- New Project Idea: Environment Variables.
- Stuck in a Rut.
- Self Therapy or Professional & Amphetamines.
- Living With Reasonable Regrets.
- Switching Cameras (again).
- Soul Purpose.
- It's About Time....
- Three Concise Truths.
- The Anxiety of Clout.
- Sharing is Therapeutic.
- Positivity, Coming Soon™.
- Fellowship at PyCon (upcomming).
- First Entry.
- On Inspiration and Tools (like languages).
- On Writing.
- On Open Source and Impactfulness.
- Seeking Inspiration, Somewhere.
- On Writing Music and Emotional Landscape.
- Poetic Expressions.