Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

What makes writing documentation unpleasant for some people, and what can be done to make it less unpleasant?

Current thoughts:

  1. Ensure the program being described makes sense (eg doesn't have too many fudges or +1s or -1s in it). You feel bad, and it's more difficult, describing a program that doesn't make sense!
  2. Conquer your fear of writing. Improve your writing skills, possibly on pleasant tasks.
share|improve this question

put on hold as too broad by gnat, MichaelT, Kilian Foth, Bart van Ingen Schenau, Dan Pichelman yesterday

There are either too many possible answers, or good answers would be too long for this format. Please add details to narrow the answer set or to isolate an issue that can be answered in a few paragraphs.If this question can be reworded to fit the rules in the help center, please edit the question.

    
Video. It killed the radio star. –  Wyatt Barnett Feb 15 '12 at 1:39

7 Answers 7

If the project was well planned and managed, the documentation should have been nearly complete before a single line of code was written. Please don't misinterpret me as advocating any specific development methodology, in particular TDD. However, every proposed feature of a program should be well described prior to work actually beginning.

Of course there will be changes, which means you'll need to update the project specification as you go. However, if done faithfully, the only mundane task is to take that specification and polish it into documentation that is ready to ship.

This avoids the daunting task of writing it from scratch after the project has been completed, and helps you to quickly identify scope and feature creep. Additionally, it helps you to better visualize the impact of changes in a way that can quickly be communicated to the client.

Finally, your testers aren't just testing the program itself, they are also testing how well it adheres to the given specification.

If done correctly, documentation is a painless process.

That being said, sometimes you will have to document something from scratch. In those cases, I highly suggest writing naturally, as you normally would and hiring a professional editor which is cheaper than you might think. Learn from the editing process.

I agree with finding ways to practice and refine your writing skills, but for different reasons. Effective writing skills make you a more effective communicator in our world of e-mail and instant messages. You'll also be refining how you communicate verbally as you begin constructing shorter, more concise sentences naturally.

Being able to write better documentation faster, imho, is an ancillary bonus. Your job is to write programs and communicate.

share|improve this answer

One reason for unpleasantness is subpar tools such as Microsoft Word. Using a good documentation tool such as Sphinx can considerably boost the fun of writing.

share|improve this answer
    
+1, Using nice tools always makes things more fun. –  David Brown Feb 15 '12 at 1:55

One of the common reasons is an inhibition in writing anything. This needs to be worked upon. Participate in online community discussions where discussions happen in a written form. Start a blog. Blog posts can be short or long depending upon what we are comfortable with. Make it a habit to use proper English in day to day written communication like e-mails.

We usually spend days trying to perfect our development environment. Be it bashrc, vimrc, editor macros, utility scripts etc. But there may not be good documentation templates. Getting a good documentation template can be time consuming especially since we are not very good at word processors. We used to have a documentation template in comic sans font. I couldn't even bear to open the file itself, forget updating the documentation.

In general I find programmers not devoting time to understand how well to use a word processor. I personally prefer to write all documentation in pure text and then later get some expert help in porting it to word processor format. We can get help from technical writers in office to learn basic tips n tricks of the trade.

Existing document may be haphazardly written. There may not be any consistency in font type and size used for similar entries. Programmers typically prefer symmetry or rule of thumb to follow. Documents that are styled in a seemingly random fashion can be a big turn off for programmers to update. The best approach will be to bite the bullet once and get the document in shape before updating.

share|improve this answer
    
amen: write your documents in text and let a tool lay it out in a final presentation format. –  gbjbaanb Feb 14 '12 at 23:41

To make the documentation something less unpleasant, I use two tricks:

  1. I use tools that help me in the task. GhostDoc for automated class members documentation, DocumentX for manual & WYSISWYG class members documentation, and of course simple tools like Flare for end user documentation.

  2. I document continously. When I've finished a feature, I document it immediately. This is essential if you want to be able to release frequently.

share|improve this answer
    
Flare is $999 ... you'd need to have some fairly hefty documentation requirements. –  Alan B May 15 '12 at 8:37

Writing documentation is unpleasant for people who are not writers, which developers are not (generally). Developers are problem-solvers (primarily), and when they begin to document some system (especially one still under development) they invariably begin pondering how to make it work or how to make it better. Then they become impatient for "wasting time" documenting the system they envision instead of making it a reality.

Writing documentation requires the mindset of an educator or helper. So if a developer can't pass responsibility for writing docs to a writer, he should try to minimize the pressure that imagining the changes causes by jotting down enough info in his ideas journal (we all have one, correct?) so he can take his mind off it for the time being (like the principle behind GTD).

Then adopt the perspective of an educator explaining to the reader what the system's behavior is. Don't focus on the order, or keeping the explanation organized at the start. You'll just frustrate yourself if you attempt to clean house while you're being creative. Document the parts you think about first, and then reorganize them later.

share|improve this answer

I agree with @Pierre 303 use a tool that isn't nasty to use. Word has its place, but for technical documentation, you generally want something a developer can use that is easier for him. I evaluated a few documentation systems and found that Asciidoc was perfect for a developer (LaTex was a bit too format-heavy, the other lightweight markup languages were good, but Asciidoc pipped them). It generates HTML (example) or PDF for those who need a paper version. (since then I've noticed Booki that is designed for books, including large techical manuals)

As a developer, I could then open the document in my editor (and store it along with the source code) and knock out a few extra pages of text that described my changes very easily. Much more easily than opening Word. it can also be merged and easily reused and the formatting is generally all you need for technical manuals anyway. Word, shmerd!

The other thing to do is to create a template to use to start things off, or you could try splitting the document file into sections so it doesn't seem so daunting.

share|improve this answer

Habitually using structure, organization, and patterns can make documentation easier. You can use the same approach with each element of the design and the corresponding documentation in a way that it becomes second nature.

Obviously this won't help the poor programmer who inherits a mess from somebody else. But if you have any chance to develop good design habits, focus on these and the drudgery in documentation will be reduced. Then make every effort to encourage others to do the same so that, if you do inherit a job, it is less likely to be a mess.

share|improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.