I have worked for several companies, but none of them had documentation high on the priority list. So most software lacked documentation, or it was not complete, or it was outdated.
So i'm asking you, do you create and maintain (technical) documentation for each project, even if time is an issue.
At my company we have "Developers" and "Architects" and part of the Architects' jobs... when they are not themselves writing code... is to write documentation. It works out nicely.
We write our software in Python and documentation in epydoc. Epydoc comes with a check command that will report errors so we get emails every time something does not fly in the documentation. Of course this doesn't cover things like subtle changes in behavior, but it does at least make sure all variables/methods/classes have descriptions.
I'd highly suggest that documentation should be executable in some respect, or at least programtically instpectable for errors if you want any hope of keeping it up to date.
You don't mention the type of documentation.
User documentation is certainly something that must be kept up to date. This same documentation can almost be seen as a specification of at least the inputs and outputs of a completed project.
Technical documentation tends to be more important as the application grows. I like to document key architecture decisions, complex business processes and inputs and outputs as a minumum.
I would evaluate the chance that the lack of documention would come back and bite me and weigh that against the extra time/effort that it would take to generate it. I would definately generate some docs for the more confusing parts of the project regardless of the cost.
Yes, we do maintain documentation, but only because it's a mandatory deliverable to our customer (contractual requirement for a defence project). That said, it's the absolute minimum that we can get away with.
My preference would be to maintain a Wiki alongside the code base, which all the developers have access to, which (I think) is the only practical way of keeping the documentation up to date. I've never seen this work in practice, however.
While one can argue that the code should document itself (which it does to some extent), for a system of any size, architectural-level documentation is essential. Relying on residual knowledge being passed between developers is a nice idea, but doesn't scale.
You should try a documentation generator that generates documentation based on your code. I really like doxygen: http://www.stack.nl/~dimitri/doxygen/
Yes, we do create and maintain documentation on each and every project. Does it take time? Of course, but in the long run it has it benefits, especially as the project goes into a maintenance phase. We do the following documentation:
For initial releases, we also create a User's Guide, which ironically comes handy for new developers who do maintenance on a project. It is easy to figure out how the application is suppose to work.
Documentation is for the interns!
(kidding, of course... well, mostly)
It depends upon the customer, the required deliverables and the product. I typically produce hypertext help for most of my products and find that to be better received than formal documentation.
I've written several user manuals over the years (screen snaps, diagrams, step-by-step how-to guides) and these have been, despite the time spent on them, received but not used, I fear.
I've been documenting a lot lately with a wiki (Tiddlywiki is what I use, and I like it quite a bit.) for my personal needs and really think that the online help is probably the most useful - I almost always go to the internet for my solutions and rarely go thumbing through my books, I think most folks do that.
The problem with formal documentation (or any, really) is that it tends to lag behind the product and is typically an afterthought or the last thing to be done. Let's face it... most of us would rather sling code than spend all day trying to write documentation.
I would say that at the very lowest level, the code IS the documentation - I know that sounds glib, read "Clean Code", and then see whether the reams of technical documentation that can be produced actaully help to understand the code, or are there simple to check a box saying "Yes, We Do Documentation", and are then never looked at again.