How can documentation writing be made less unpleasant?

Question

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.

Answer 1

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.

Answer 2

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.

Answer 3

Write it at the same time as the code.

Answer 4

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.

Answer 5

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.

Answer 6

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.

Answer 7

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.

Answer 8

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.