Reply to: Have you ever worked on a project with any decent documentation?

[MarillionFan]

Indeed. Did you get anywhere with it?

I have my own tried and tested standards for documentation which I have often been praised for.

Please don't own up to our off line conversations btw, it rather lets the side down on our on board rivalry.

Bedwetter.

[original PM]

one of the key things is ensuring that whatever document hoops you need to jump through you ensure that the documentation is easy to read and fit for purpose...

too much an no body reads it too little and it is of no use.

but ultimately my experience has found that it is knowledge in people's heads which is the biggest help - as often documentation is not clear enough or does not contain enough context to be of value

on another /similar note

is it a benefit if the BA and the PM have knowlegde of the system that are being developed.

My expereince is that if they do not the requirements for example have no real context and are of little value when trying to actually drive out development needs.

[suityou01]

A conversation we had earlier in the year.

Indeed. Did you get anywhere with it?

I have my own tried and tested standards for documentation which I have often been praised for.

Please don't own up to our off line conversations btw, it rather lets the side down on our on board rivalry.

[Mich the Tester]

Right. Totally agree.

Given that there are standards for Project Management, Coding, Design Patterns, Testing, Data modelling etc etc is there a standard for producing quality documentation?

Standards; practices and approaches that somebody says worked for them, got a few people together and wrote a book about them and set up a club called the 'International Organisation for Standardisation of ...'. In other words, tosh. Use your brain, agree an approach with colleagues and do what you believe will work.

[MarillionFan]

Right. Totally agree.

Given that there are standards for Project Management, Coding, Design Patterns, Testing, Data modelling etc etc is there a standard for producing quality documentation?

A conversation we had earlier in the year.

[suityou01]

Most documentation tends to suffer the same problem as most of the code it's written about, i.e. over complicated, verbose and full of unnecessary crap.

There's also the problem that some developers (and managers who used to be developers) have the opinion that any time spent not coding is time wasted

Then there are also companies with ridiculous documentation templates which need to be followed at all times and bloat what could be a 1 page diagram with a bit of text to 10 pages with an abstract, introduction, intended audience, distribution lists, contents page etc...

There are some good wiki systems which can be used on the corporate system which are a much better idea than hundreds of word documents. The beauty of the wiki pages is that high level docs can easily link to lower level technical explanations meaning that a reader only needs to dig as deep as they need to.

Right. Totally agree.

Given that there are standards for Project Management, Coding, Design Patterns, Testing, Data modelling etc etc is there a standard for producing quality documentation?

[Spacecadet]

Most documentation tends to suffer the same problem as most of the code it's written about, i.e. over complicated, verbose and full of unnecessary crap.

There's also the problem that some developers (and managers who used to be developers) have the opinion that any time spent not coding is time wasted

Then there are also companies with ridiculous documentation templates which need to be followed at all times and bloat what could be a 1 page diagram with a bit of text to 10 pages with an abstract, introduction, intended audience, distribution lists, contents page etc...

There are some good wiki systems which can be used on the corporate system which are a much better idea than hundreds of word documents. The beauty of the wiki pages is that high level docs can easily link to lower level technical explanations meaning that a reader only needs to dig as deep as they need to.

[suityou01]

All documentation is tulipe cuz it gets out of date the moment the software is released.

Well except at least a high level architecture diagram - at least I have found that is the one document worth keeping upto date as its a starting point of where to be looking next.

Which is precisely the document I need.

[MPwannadecentincome]

All documentation is tulipe cuz it gets out of date the moment the software is released.

Well except at least a high level architecture diagram - at least I have found that is the one document worth keeping upto date as its a starting point of where to be looking next.

[doodab]

That's the Gangnam style version but if the project were properly planned there would be exit criteria for each phase of work that would require signed off documentation.

It depends on your idea of "properly planned".

Bear in mind that most people's idea of project planning is at least loosely aligned with PRINCE2. Personally I find it bizarre that this way of doing things has found overwhelming acceptance despite it's origins in the UK government, who lets face it are an organization world famous for their inability to deliver IT projects.

Documentation should add value, not be an end in itself. Sometimes that means that upfront design or exploratory prototyping is required in order to flesh out ideas or confirm assumptions, and while that has value at the time it's done maintaining it during later phases is generally more of a millstone. There is a sweet spot of useful documentation that explains the big picture and how the elements fit together in a way that the code usually can't (especially when dealing with modern frameworks) but anything beyond that tends to add overhead without benefit. The end result of management / process insistence on it tends to be that people cut and paste vast gobs of code & config into a word document to fill up their "quota" and you end up with out of date and misleading documents that require significant maintenance. That's time that would usually be better spent making the actual codebase more readily comprehensible.

[suityou01]

Yes, that sounds familiar. Bottomline, just comment your code properly if you are a dev, and screw the rest. The documentation gets out of date very quickly due to the revolving door of changing specifications. By the time someone delves into your hard work, it would be found woefully inadequate due the system being changed drastically by some tuliphead sitting way up the chain..

That's the Gangnam style version but if the project were properly planned there would be exit criteria for each phase of work that would require signed off documentation.

[tranceporter]

After a failed project last year (twice) I picked up the mantle & produced a list of documentation required. 16 seperate BRD documents, eventually reduced to 10.

Diagrams, documents, workflows etc. I wrote 7 out of the 8 so far & it has near killed me. Even gave them a working prototype for phase 1 which contained calculations & the output is identicial to what would work.

First phase has just finished & I personally have come into huge criticism. The developers, even with all the documentation reduced it to stories, then piece by piece developed it without understanding the whole picture. Then at the end, they complained that the documentatoin had been too high level for them (I needed sign off from the business) & because the UAT scripts went good enough they'd had trouble testing their own work.

FFS! I have near

Yes, that sounds familiar. Bottomline, just comment your code properly if you are a dev, and screw the rest. The documentation gets out of date very quickly due to the revolving door of changing specifications. By the time someone delves into your hard work, it would be found woefully inadequate due the system being changed drastically by some tuliphead sitting way up the chain..

[OwlHoot]

Just thinking. Can't remember the last time.

Architecture diagrams, ERDs, data dictionaries, system specifications?

Just piling through some code but I've not got a clue where it's used in the main solution so I need to do some hunting around. This will take a few hours. Would take seconds if there was documentation.

Worked with some beautiful documentation as functional & design specs prepared in advance, but in the end the result bore little resemblance to it!

As Field Marshall Helmuth von Moltke said, "No battle plan survives contact with the enemy", and the same could be said of most specs prepared before coding starts (although even so, it's better at least to try)

[Mich the Tester]

All my code is documented in C++. I hope you don't understand C++ because if you do you'll see what a load of BS I've written.

ftfy

[doodab]

So basically you charged your client an awful lot of money, and did a whole load of completely pointless work that contributed nothing to the project.

Well, he is a permie....