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

[MarillionFan]

Documentation is a rarity these days. Will organizations being pushed to deliver more and beat the competition, the onus is always on getting the functionality tested and out of the door to be "first in the market to offer xyz". That being said, most business analysts dont have much of a clue of how the system works either. All they do is pass yoour query to one of the senior fats cats who has been fossilised in his position for 15 years, and wait for him to answer in an "AGILE" way.

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

[VectraMan]

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

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.

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

[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

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

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

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

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

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

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