The LAST thing my team ever gets around to is the documentation. It is an important piece of the overall puzzle but it is the one we can rarely find.
So what do you use to make the process as easy as possible?
We have used screensteps.com in the past which makes things a bit easier. But it can still be a bit cumbersome.
Unfortunately, some simply can't do a decent job, and others who don't want to do it, will do a poor job if required to do it. Thus, the rest of those who are capable of doing a good job are punished by having to do more than their share.
If you are talking about user documentation, hire a competant technical writer.
If you are talking about programmer documentation, well, it DOES need to be done. Perhaps make sure the person who wrote the documenation has their name on it as the go-to person when there are questions. If there are no or few questions, they did an adequate job, and if they are bothered by a lot of questions, they'll fix it for their own peace of mind.
Documentation is a tricky term since it involves different artifacts and different tasks, what do you mean by documentation?
User manuals? Screensteps can be used for that. Most companies hire special technical writers to do user-friendly documentation.
Function headers and API documentation? That's a different story. The "official" guideline (at least for Java) is to capture everything - complete specifications. The agile approach is to document only what's important. I published a study that shows that detailed header documentations tend to actually distract users. There is a relatively small list of important "directives" and "caveats" that need to be conveyed. PM me or send me a comment if you want more details on that and I'll detail more. I'm avoiding it now since I'm not sure what you meant.
I also had a tool that lets you record a narrative of what you do as you work, and it ties it to a log of your edits and actions, that establishes some traceability though it's of course not documentation.
Documentation should be an integral part of your plan and not just a bit tacked on the end.
We have a requirement that documentation for parts of the system are a deliverable for those parts, so that it's done interspersed with the actual product development. Like unit testing results, the parts aren't considered complete until they've had some reviewed and approved input to the documentation process.
But, as to the tools, OpenOffice.org with our own customized templates, along with Hypersnap for screen capturing, is all we use.
The worst thing you can do is leave documentation as a distinct step at the end of you project. Here are some things we do in my team to ensure documentation gets done:
In my experience, the best approach is one that includes documentation as one of the continuous activities that are always going on - just as you shouldn't leave all the bug fixes for the end of the project, neither should you leave all the documentation.
Of course, "Documentation" is a generic term that could apply to any of a dozen different artifacts - the "best" approach will depend on what is required, which in turn depends on the target audience.
Here are some thoughts ...
Developer Documentation - set up some kind of tool to harvest information from your source code. If you're a .NET shop, use SandCastle; for Java, use JavaDoc; for Delphi, Time2Help; whatever your environment, find a tool that will harvest metadata and comments from your source and compile that into a usable form. Integrate the documention into your builds - daily if possible.
Release Documentation - check out what's available from your bug tracking tool for documenting the fixes/changes/features in each release. JIRA can generate release notes based on the "fixed in" release, other systems have similar functionality.
Support Documentation - encourage your developers to make notes about things that might be an issue for production. A wiki is good, as is an email alias. Whatever system you use, keep the "barrier for entry" low so that you capture the data. Having the information is more important than having it pretty. Hire a student to collate the details together.
Tip: Make the document fault/fix focussed so your admins don't have to read the whole thing.
End User Documentation - not everyone learns well by reading, so think about other possibilities. Record a screencast using Wink, use screenshots. If you're running automated testing of the GUI for specified scenarios, capture a movie of those steps to demonstrate to end users.
Don't save your documentation till the end! I know that sounds trite and simple, but it really is by far the best suggestion I have to give on that. There's a certain self-reinforcing principle going on there, as well; because your documentation has been such a slog in the past, your team desperately wants to avoid it; so they put it off until the end of the project; when it becomes a slog.
Document as you go. Insist on good Functional Specs, good Design Specs, keep them up to date, insist on documentation standards being upheld in code reviews, etc. Yeah, it's a hassle then too, but... if you document as you go, you won't find that you're in the situation of not knowing what something does because somebody didn't document it when they wrote it 3 months ago. Because when you're in that situation, yeah, the documentation process sucks.
My personal opinion is that the specification of the project should serve as a base for documentation where the document is somewhat of a living breathing item during the project where one could color code what parts are done, what parts aren't and reference other documents that may contain more details if necessary. Sometimes all that is needed is enough of the basic, "Here is how you use this," rather than explaining why the syntax is blah blah blah.
Most teams that resist documentation do so because they don't know what good doc looks like, or how to produce it. The team leader or manager should provide an example or even a template for what they expect the doc to look like.
If your team has no significant skill at making product documentation a work of art, then remove that requirement. Ask for rudimentary documentation if you can't get great documentation. Once you have doc that is complete and literally true even if isn't entertaining, then at least you have something you can improve upon. You can also use this as "raw material" that you can hand off to a professional tech writer.
My criteria for documentation is that it be:
Buy a copy of "The Elements of Style" by Strunk & White for each team member who writes doc. Let them read it on company time. Another good book is "Read Me First! A Style Guide for the Computer Industry "
Finally, it's important that the schedule treat writing documentation as a legitimate task, with non-zero time allocated to it. Maybe the team members don't want to write docs because they get no "credit" for having done it.
There are several types of documentation. Don't try to force one document to serve different needs, and be clear about. For example, in order from easiest to hardest for a developer to write:
Be clear about which type of doc you expect the developer to be writing. It's hard enough for a developer to write one type of doc, so make their assignment clear, specific, and structured.
One of them will have to do ONLY documentation.
He can use LaTeX or Google Docs(allows people to work together) to put together
all the pieces that the other members of your team bring him.
Documentation for code written in the D programming language took a big leap forward with the introduction of Ddoc, a tool that reads D source code and automatically generates html documentation from the documentation comments. This saves about half of the work involved in creating the documentation, the tedious half.