Have you ever worked on a project with any decent 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]

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?

[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.

[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.

[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.

[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.

[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.