Documentation Conundrum

[Onyxpurr]

I am the only analyst/programmer for my office of 280 people. I was hired on to automate a majority of the processes that are currently manual. I love my job!

However, as expected, my time is stretched extremely thin. Bewteen the programming, the data analysis, training, and other things, my documentation usually falls to the wayside or is incomplete after revisions.

What tips do you guys have to keep up on documentation or even make it a little easier to put together and keep updated?

 

[sleipnir214]

<sarcasm>
Don't. If it was hard to write, it should be hard to understand.
</sarcasm>

What kind of documentation are we talking her?

Code documentation is one thing, an application user's guide another, and an application administrator's guide another.

Want the best answers? Ask the best questions:

http://www.catb.org/~esr/faqs/smart-questions.html

TANSTAAFL!!

 

[SQLSister]

Well I find code documentation easiest if I use it as kind of an outline for what I intend to do. I write out the steps in comments and reaarange these till I think I have the process down and then I code.

Requirements documentation can be on index cards if you want or the notes of meetings with users, just file it with the project folder. Helps to get the authoizing initials on whatever you use if there is a decision maker who must approve things. It's harder for him or her to say they didn't agree to that later if you do and it cuts down on the frivolous requests if they know they can be held accountable for authorizing them.

I also keep all emails for a project in folders in Outlook and design my file system so that all the relevant documents for a particular project are located together. This helps when you have new employees who need to be brought up to speed.

Documentation of requests for services can be a simple form that they fill out to request something. A database for this and an electronic form is great but it's often faster to gen up a paper form and use it until you have some spare time to create the database and user interface. The important thing is to get this rolling as soona as possible, you can make it more effective later.

If someone requests something verbally or by the phone, you fill in the form as they talk to you. In fact once I had a job where I managed 30 manpower studies happening all over the world. I got in the habit of recording every phone call as it happened on a phone call form and keeping them in a clipboard on my desk. Since I always recorded the date and time and I had a paper record (you could do this in a database but this was so long ago I didn't have a PC on my desk!), I won every argument about what was asked for or who said what when. Since I recorded as we talked, it never took any more time than the conversation.

What did take more time but was worth it, was I sent a memo to the people involved whenever we made a decision. So if we decided the project would need to be complete by Dec 12, I sent them a memo (this would be an email now, of course) restating the decision and asking them to respond only if this was not what they thought they had agreed to. Since no one ever bothered to respond, I again won all the arguments about what was decided. Now you can't do that with every tiny decision, but it is a great tool to document major decisions without.

User documetation of the system, now that's a toughie. In a small IT group I think this rarely gets done. If you keep track of the problems people come to you with, and the solutions, you can often create an FAQ for them if needed fairly easily. Or use your notes of recurring problems to do a short user training session.

 

[benlinkknilneb]

On my last big project, I kept a journal. I'd take 10 minutes at the end of each day and write out all the things I'd done. It made it really easy later on when I tried to test a portion of the program, put together a user's guide, or anything that required a good overview of what was happening.

 

[Onyxpurr]

These are great tips!! Thanks!

As for the questions of what documentation, pretty much all of it. I do follow these to a cerain extent. I have been meaning to create an online form for requesting stuff for the users, but I can't seem to get my DBA to create the sql table for me (another issue for another forum).

My main concern though is the kind of documentation that would be benficial to any programmer coming in after me. What if I keeled over tomorrow and someone had to come in? Or more importantly (to me), I get requests to change a query or report months after I created the initial one and I need to remember why I created it that way? Or what is associated with what?

 

[MDXer]

If your main focus is aiding other programmers then inline comments can be useful. I do this when I know something will be passed on to someone else. I describe the purpose of the function and then any complex logic being used.

&quot;Shoot Me! Shoot Me NOW!!!&quot;
- Daffy Duck

 

[BJCooperIT]

I document in my code well. When I begin to write user documentation, I copy all the comments from my source code and paste them into a Word document. That becomes the starting basis for my user documentation when I add screen shot captures.

[sup]Beware of false knowledge; it is more dangerous than ignorance.[/sup][sup] ~George Bernard Shaw[/sup]
Consultant/Custom Forms & PL/SQL - Oracle 8.1.7 - Windows 2000

 

[nexcar]

Documentation is a constant struggle for me. I'll be programming for a few hours, get up to stretch, and notice that none of my VB code is green(comment code). Mainly becuase I know what it does, and what its doing. If I comment a line it has to be something dramatic or somthing I know I'll forget later. As for user manuals, somewhere on the Visual Studio CD is a help system compiler. This is what my company uses for compiling HTML help files like in all Windows applications. I hate writing these because all the screen shots and proceedure steps take so long to write. You also have to 'dumb-down' your thinking to be able to look at you application from a users perspective. Its hard to use your app as a new user when you know whats going on in the background. But once you learn how to do this, you'll be on your way to true programmer-hood.

RUN FunnySignatureMessage

 

[pmonett]

As a rule, I've always hated writing documentation of any kind. I feel it takes valuable time from developing functionality and maintaining existing functionality.
However, over eight years of consulting, I have found that I despise even more having to work on an application for which not only is there no documentation, but the code itself is badly written, without any functions or subroutines to help clarify what is going on and why.
So, after all that time, I admit writing documentation is a necessary evil.
Yet, I am more interested in code that is rather easy to comprehend. There are different ways of writing code, whatever the language used. One is to pile line upon line of hopelessly entangled instructions that will invariably elicit (in the mind of the next guy who it fell on to modify) a gut reaction calling for a complete rewrite.
A different way is to break the procedure into steps, break the steps into smaller portions, and code the little bits into bigger bits into a main sequence that, suddenly, becomes much more readable.
By doing that, and commenting code when useful (;need to get resource A because field X has category info), you can almost dispense with writing a full documentation for the next guy. If he is worth anything as a programmer, reading your code will TELL him clearly what is going on and why.

Clear code is more important than documenting a mess. Of course, the best situation is having code that is clear to read, and documentation that outlines all the procedures, the function calls, and the scope not of each function (that should pretty easy to determine) but of WHY that function/procedure is necessary.
More and more I find that it is not the CODE that needs documenting, but WHY the code was written in the first place.

Of course, writing anything still requires time.

Pascal.

 

[jrbarnett]

When I was given my notice period from a former employer I was asked to document the projects I was working on. That meant, as far as I was aware:
* Comments in code up to date and understandable.
* Description fields in database filled in and described.
* Entity relationship diagram showing database structure, referential integrity, primary/foreign keys of each table.
* Detailed database documentation listing every field in every table, showing format, required or not, pseudo code for the actual VBA procedures (so if they didn't understand my actual code, they would have a good idea as to what was going on and why).
* User documentation including details of business processes that the database supports, created in conjunction with the client, with FAQ's etc.
* I considered creating UML diagrams, but none of the other staff understood it particularly well.
* Details of restricted access areas in the software - so they could find out how to regain access if the password was forgotten etc.

Basically, what I did was imagine myself in the receiving end of the documentation and ask what I would like to know if I was coming to this from nothing.

John

 

[KenCunningham]

John,

considering you were working out your notice, those requirements certainly appear to be above and beyond the call of duty, and it must have been rather galling to complete them I imagine. However, I guess we'd all do it if it led to a favourable reference for future employment. Good luck.

 

[jrbarnett]

Ken,

It was a bit nerve racking given that I was asked by the directors to do this. On the other hand it was easier than brain achey programming problems and a nice change to sitting in front of the VBA editor.

I have not had anybody from the company contact me to ask to clarify anything or ask questions about it.
As it is now over 18 months since I left, that is unlikely.

John