[Discussion] Pre project documentation

[DeanMc]

I have an issue that I feel many programmers can relate to...

I have worked on many small scale projects. After my initial paper brain storm I tend to start coding. What I come up with is usually a rough working model of the actual application. I design in a disconnected fashion so I am talking about underlying code libraries, user interfaces are the last thing as the library usually dictates what is needed in the UI. As my projects get bigger I worry that so should my "spec" or design document.

The above paragraph, from my investigations, is echoed all across the internet in one fashion or another. When a UI is concerned there is a bit more information but it is UI specific and does not relate to code libraries. What I am beginning to realise is that maybe code is code is code. It seems from my extensive research that there is no 1:1 mapping between a design document and the code.

When I need to research a topic I dump information into OneNote and from there I prioritise features into versions and then into related chunks so that development runs in a fairly linear fashion, my tasks tend to look like so:

1. Implement Binary File Reader
2. Implement Binary File Writer
3. Create Object to encapsulate Data for expression to the caller

Now any programmer worth his salt is aware that between those three to do items could be a potential wall of code that could expand out to multiple files. I have tried to map the complete code process for each task but I simply don't think it can be done effectively. By the time one mangles pseudo code it is essentially code anyway so the time investment is negated.

So my question is this:

Am I right in assuming that the best documentation is the code itself. We are all in agreement that a high level overview is needed. How high should this be? Do you design to statement, class or concept level? What works for you?

[NeedSomeAnswers]

Am I right in assuming that the best documentation is the code itself.

Well i work writing commercial software, and for us for new features or enhancements we do create a design spec but it is at a high level. It explains what the feature is designed to and does not describe the code at all.

We have coding standard that we follow that determine how we implement the code (and obviously our own experience as well).

If we were designing a large project from scratch then we would be expected to do slightly more low-level design, but again it would explain the relationships between the various objects and classes e.t.c rather then go down to the detail of explaining the code itself.

[DeanMc]

That is how I thought it should be but I am afraid I may be digging too deep into the code when designing.

[mendhak]

Functional diagrams will help you focus on the project direction. Going too level can create problems and overheads in terms of changing it as you go along and find new problems and solutions.

At the same time, the best documentation is not code itself, that's just something lazy programmers say. Comments help too! Making the diagram available somewhere for the 'next' developers to look at along with a description/overview of how that specific piece of functionality works helps immensely as they get a good idea of what to expect rather than having to try and read a story.

[abhijit]

The useful project documentation is in code comments.
The useless documentation is in the Help Files.

[techgnome]

If you're writing code in your design, you've gone too far.

Design documents should be of varying levels that bridge the gap between the requirements and the actual code. Or stick of measurement is: Does the design document describe sufficiently that if given to a developer with no background in the system, they could write the code with minimal instructions?

Example:
Requirement: Data needs to be saved to the database.
Design:
1. Save data
1.1 Button will need to be added to screen XYZ
1.2 Button will use fields A, B, C from screen and send to data access component
1.3 Data access component will initiate call to stored procedure passing in A, B, C
1.4 Store data in database
1.4.1 A will be stored in fld1
1.4.2 B will be stored in fld2
1.4.3 C will be stored in fld3
1.4.4 If A & B already exist current record will be updated with C


and so on... at design you should be caring about HOW... just the WHAT. The development cares about the how.

-tg

[Shaggy Hiker]

I write extensively. In fact, nobody really wants to read what I write.

I work in a situation where there are just a small number (hard to say how many, exactly, but half a dozen give or take a few depending on how you count some people), each of whom has their own project. I have started on the only collaborative project that we have ever undertaken, yet the other half of the collaboration is still mired in his last project, and will be for a few more months. Therefore, even this project is solo. It will also be HUGE for a single Lone Ranger style coder. The expectation is that it will entirely replace a program I wrote over a decade ago, which was about 20k lines and over 70 forms. The current project more than doubles the scope of that original program, and can be expected to more than double the size of it. Furthermore, I have two other projects that I am currently supporting, along with other demands on my time. Documentation at a variety of levels is critical to making progress at all. Each piece has to be worked through and thought out in great detail, especially since the project involves some math that is more interesting than your typical business app.

I write one set of documentation to share with the other collaborators who might, eventually, participate in writing parts of this code. This includes documentation of interfaces and dlls that can act as a reference for somebody who doesn't want to wade through the code, as well as documentation about why this particular design was chosen, so that others won't have to repreat the days, weeks, and months of thought that went into this (I am the most knowledgeable user of this data, having worked with the data, and thought about the program design for the last twelve years, so when I need to consult the user group, it usually just means going for a long walk to think it over).

There is also a working document which covers my thoughts on individual portions of the code. Whenever I figure out how a particular piece should work, without having the time to implement the design, I write up the concept in the working document. I also use the working document to hash out the various options for solving any particularly tricky problem, since I type far faster than I write. Ultimately, this means that the working notes holds a mish mash of useful and dated material of things already done, things that will eventually need to be done, and things that never will be done. As I definitively identify the first and last of those three, I move them to a different document. This keeps the working notes down to a couple pages, while retaining the steps taken along the way so that I can review them at a later date.

The notes give me references as to what I was thinking, and what I had already covered, once I have forgotten that I even went there.

[DeanMc]

In the end I went with mind mapping. I find it a great way to have everything in the one place yet still somewhat organised. I realise though that they may not be great when shared (ive tried, it doesn't work). To counter this I find that once a piece is implemented from my thoughts (on my mind map) its easy to write documentation since I am documenting what has already been written.

[chris128]

Lots of useful information in this thread for me as I was going to ask the same question myself sometime soon so thanks for everyone's input