Document first , document later

There is a great debate in my head, what is best – to document first , or to document latter. The wanna be engineer in my head would scream “Document first!”, but my practical side, the one that has been into the trenches, that has seen things, horrible things would say “Document later!”. How to reconcile those two opposing views?

Documents can be generally be placed into two broad categories, those that are:

• Generally written before development


• Generally written afterwards development

Why do I say Generally? Because in software development nothing is set in stone, and everything is fluid, thus documents cannot be said to have been written always before head or afterwards a piece of software is developed( class, module, library etc.) . A set of documents could be generally written before head, like requirements or the high level architecture, and some are generally written afterwards like in some cases detailed API technical specification.

What makes a document fall into one of the two general categories. Two things :

• Type of document


• Current state of the software life cycle

The Type of the document generally dictates when a software piece will be written. Like, requirements or the functional specification or something like that which is generally needed before a piece of software is written. And some which cannot be (or can, but albeit very hardly depending on the skill of the developer and the knowledge of the system), like detailed technical specification which is not ever accurate when written first and is ever (hopefully) updated once a particular piece of software is written.

The other most contributing factor is the current state of the software life cycle a team find its self in. When developing a green field software it is generally best to do the documentation first ( I'm not discussing waterfall here, you could develop module after module, and before each module write the technical documentation for it before going into development), but when a team finds it self knee deep in a brownfield development project, which generally doesn't have any documentation what so ever, which isn't even commented properly so you cannot generate an API spec automatically which is remotely useful to anyone, when you need to fix unknown defects, when you need to implement a piece of functionality and don't know how to place it inside the project and how it is to be connected to everything else, writing documentation first could be and exercise in futility since you don't know enough about the system. This will change gradually during brownfield development when you will reach a state where writing design documentation first would be a better choice in terms of quality of work and writing speed place into the construction of the document.

So, what to say to may two different parts? It depends. And that is the only answer I can give them, which places my little self once again on the verge of a nervous breakdown due to over thinking so simple things. But documentation is important, some cannot see that, but those cocky bastards will soon find them selves trying to remember how they did that, or where somebody placed this and how is generally this implemented and so on, and will loose valuable money debugging the thing out of its life in order to find something which would take five flimsy minutes to read. Who is stupid now, ha?!