How much documentation do you do?

O

oober

Expert Member
Joined
Apr 3, 2005
Messages
3,080
Reaction score
84
Location
Gauteng
Since I have to start doing the specs for a couple of projects that needs to be completed in the coming weeks I was wondering how much documentation my fellow developers do.

Do you just comment your code and view that as enough or do you write a fully fledged technical specification document?

Do you have specification documents for your projects that must be signed off before development starts?

How much time do you spend on documentation?

Would love to hear what you do.
 
about what i do

1) comment my methods as to what they do, and then inside them where its something out of the norm

2) on roll out, how to manual

3) on maintenance note changes and updates
 
Necuno said:
about what i do

1) comment my methods as to what they do, and then inside them where its something out of the norm

2) on roll out, how to manual

3) on maintenance note changes and updates
Click to expand...

So how are the specifications handled? Do you have a person who does the documents?
 
oober said:
So how are the specifications handled? Do you have a person who does the documents?
Click to expand...

The technical and application spec is written before hand and then gone over with the client (being the company itself). Then when both sides are happy- we start to program.
 
No, I don't just "comment my code". The problem is that I'm the analyst AND main developer. The company has some blue-sky ideas of what it wants, but its up to me to realize their dreams AND analyze the market requirements. We don't just build custom systems for business requirements. We have a strong suite of (web-based) products that we sell to the greater sub-Saharan African region. We're slowly but surely branching out to the Australasian region as well...

So, to get back to the point. As developers, we share ideas in the company and, from time to time, draw up a draft spec of what the functionality will entail, if only to please current and future customers of what they can expect. We try to stick to the spec as closely as possible, but (as is the nature of IT), it changes significantly most of the times. We plan out database structures with rudimentary ERDs on a nice big white-board on the wall, but the proof is in the pudding... :p

I strongly believe the new developers should be trained on the philosophy of the system BEFORE they even start touching the code - that can sometimes take up to a month. They usually get placed in a testing / training position first while they learn the ins and outs of the system. After understanding what the company / products are all about, they have a better understanding of what they will be coding. Its a lot more valuable than some simple comments made in the code...
 
Necuno said:
The technical and application spec is written before hand and then gone over with the client (being the company itself). Then when both sides are happy- we start to program.
Click to expand...

So you are one of the lucky people who gets a document handed to them and can then start development? Nice
 
I do a feasbility study, then i do a techinical review, i then have todo a scope prototype, i then have todo a techinical spec (api and stuff), i then have todo projected time lines, after which if we are developing any of our own stuff, we have todo white papers on those. so alot of documentation. Not that we follow them hahaha
 
semaphore said:
I do a feasbility study, then i do a techinical review, i then have todo a scope prototype, i then have todo a techinical spec (api and stuff), i then have todo projected time lines, after which if we are developing any of our own stuff, we have todo white papers on those. so alot of documentation. Not that we follow them hahaha
Click to expand...

Let me see...
Techinical Review: What does this entail? Is it all the technical requirements etc.?

Todo Scope : Is this like an initial Work Breakdown Structure?

Todo a Techinical Spec : You then expand your WBS to include more technical detail?

Todo White Papers : What are these?

Edit: I have found that there are so many different terms for the same thing that it can really get confusing. :D
 
Last edited:
FarligOpptreden said:
I think he meant he has "to do" those documents... :p
Click to expand...

lol yeah..

white papers are techical details on the types of things that might be invented or designed during the course of the development, like say you develop a new method of transmission via a new dataformat developed etc..
 
oober said:
Let me see...
Techinical Review: What does this entail? Is it all the technical requirements etc.?

Todo Scope : Is this like an initial Work Breakdown Structure?

Todo a Techinical Spec : You then expand your WBS to include more technical detail?

Todo White Papers : What are these?

Edit: I have found that there are so many different terms for the same thing that it can really get confusing. :D
Click to expand...

scope prototype would be an initial design concept of screens, and general look and feal.

The technical scope would be the class break down, the inheritance, basically all the stuff to do with the innards of the system/code/etc.. different guide lines to follow whilst developing, also good when bringing on new developers so they have a deeper understanding on what they doing.
 
semaphore said:
lol yeah..

white papers are techical details on the types of things that might be invented or designed during the course of the development, like say you develop a new method of transmission via a new dataformat developed etc..
Click to expand...

Ahh ok so you call them white papers. Terminology is a b!tch.
 
semaphore said:
scope prototype would be an initial design concept of screens, and general look and feal.

The technical scope would be the class break down, the inheritance, basically all the stuff to do with the innards of the system/code/etc.. different guide lines to follow whilst developing, also good when bringing on new developers so they have a deeper understanding on what they doing.
Click to expand...

Ok so if I understand you correctly you are basically talking about technical documentation which would entail all that you have mentioned.
What about the normal documentation that gets drawn up with the client?
 
that would be done after a scope prototype, the client would see that, and then you would break it down and remove or add extra features. You would then do the finial scope document, this would ensure that you do not get scope creeps
 
semaphore said:
that would be done after a scope prototype, the client would see that, and then you would break it down and remove or add extra features. You would then do the finial scope document, this would ensure that you do not get scope creeps
Click to expand...

What development process are you following? It's starting to sound like agile development?
 
oober said:
So you are one of the lucky people who gets a document handed to them and can then start development? Nice
Click to expand...

yes and now; if its my project from the start i have to do it :p
 
You must log in or register to reply here.
Back
Top
Sign up to the MyBroadband newsletter
X