Slashdot Mirror
Beginning Project Documentation?
mirthe_v writes "Hi, I'm working for a small webcompany (about 20 people), with ColdFusion programmers and designing staff. We all work on a bunch of projects (Internet, intranet, cd-roms, etc.) on the same time, with different people and different or no methodologies. There is an ever growing need for documentation, but we have no idea where to start."
mirthe_v continues: "I was just wondering how other people/companies keep track of their current and older projects.
Do you put stuff in a database, if so, what about all those diagrams and handwritten notes.
If not, do you store things in a folder per project, and how do you then stop documentation from getting lost and making sure people store things where they should.
"As I said, I don't know where to start, especially since the staff varies greatly in the need for documentation, technical background, experience with writing documentation and even different languages (English and Dutch).
"Please share all your thoughts and experiences. Cheers, Mirthe""
It's very, very easy to let documentation fall out of date, but even old documentation is preferable to none. Your most important job here will be to get people in the habit of creating and committing documents to some kind of record. Ideally, you should have a source control system, and you can easily place documents under source control as well, so you can go back to previous versions of documents or recover in case you accidentally overwite documents or lose something important in an overly ambitious cut. Be at least systematic enough to put design documents in appropriate project folders. Set a good example and people coming after you will look at what's already there as a model for making their own documents. Use descriptive file names. Naming something 'design1.txt' may seem simple enough now but three months later you'll be wondering if that was your first rough or final design concept, whether it includes feedback from the customers, and so on.
I've found that CVS works well as a document repository. Any sort of version control system is well suited to the task of keeping documents. The only trick beyond that is establishing an organizational structure for it.
As far as organizational structure, base it on the development process you use. So in each phase of development, you have the documents needed for that phase seperate from everything else. If you have deliverable documents, put those in a directory and then have subdirectories for any supporting material.
That's a suggestion. I would highly recommend sitting down and formally structuring this. If everybody knows where the documents are, and where to put new documents as they generate them you'll have a lot easier time of things.
This sig has been temporarily disconnected or is no longer in service
Give each person a real lab notebook, the kind that you can't rip pages out. Require that employees use the lab notebook to record project notes, observations, and thoughts during their work day. When the employee resigns or is fired, the notebook stays. These notebooks create a threaded history of projects and the issues encountered along the way. The value of well maintained lab notebooks is truly priceless. These notebooks become the raw material for more formal documenation, and serve as documentary bridge between the project requirements and its actual implementation.
I know this may sound evil but when a company is as small as yours, worrying about ANYTHING besides making money and pleasing the customer is detramental. You may get people who want do things "the right way". Fire them QUICKLY!! The "right way" people are always the ones who blow schedules and bring down companies. The only way is the way that ships your product and keeps customers calling. As you grow you can begin to focus on some level of procedure, documentation etc. This comes from someone who has seen "right way" people destroy a company and keep those people out of his company which has not only survived but still flourishes.
I do not now, nor have I ever, worked for and OSDN company. That being said:
Documentation does not live in a vaccuum. For every project, you want a certain set of communication tools: Revision Control, Mail lists, Documentation, Releases, etc. For my old company, I set up an example site of sourceforge running of my workstation. The idea was to set up a quick and easy project website. SoureForge (the project) had everything we needed. One of the nice things is the document erepositor portion. Since SF is by project, documentation is already per project. Etc, etc.
Php groupware also looks to be promising, as does phprojekt. I am not sure if there is an open source Cold Fusion based solution, but that may suit your needs better, since it sounds like you have some in house exp. with it.
Open Source Identity Management: FreeIPA.org
In fact this doxygen was only part of the solution, our research projects had other documentation which required addition, however we simply had the developers get into using LyX and had the doxygen script merge in the static docs with the code documentation. Made for a nice doc tree which was easy to update (and if you really want to get fancy every once in a while, import into LyX and whip up a tasty DocBook). Of course the developers has to conform to the commenting style required, however if this is a problem for your development team, then the whole 'team' concept isn't going so well.
If you don't use CVS and/or doxygen, and those tools don't fit into your workplace (although CVS should be used, IMHO). You could easily whip up a php or perl script to merge TODO and Changelog files, this is of course assuming that all the developers use these files to track their work, which they should do anyhow (at least in some form). It would be trivial to whip up a parser in perl and merge those files into some sort of report. Thus the whole Practical Extraction and Reporting Lanuage thing...
Part of FuseBox is FuseDoc which is a XML based spec for putting docuementation inside your CF code. By using Fusebox and FuseDoc you can break your web apps out into separate modules that work together much like different objects in C++ or Java. This allows you to have multiple people working on an app at the same time, while also separating your content from programming logic. I have used this approach in several web apps and it has worked well. Couple these techniques with something like CVS and some organizational programming standards (make standards that make sense!) you should be able to improve your work enviroment.
I would love to use docbook but are there any WYSI-Frickin'-WIG tools which will allow lusers to edit documents. I tried with lyx a while ago and gave up after a brief struggle.
Try asking your average windows dweeb working on ms word to write documentation which is version controllable as well as readable across both windows and unix.
Are there any GUI tools which allow you to edit docbook without having to bother with tags?
Do you have one of those obnoxious newbies programmers who fancies himself a total hax0r, creating variable names like "it3r80R" when a simple "i" would do, or putting hundreds of little in-jokes and wisecracks throughout the comments? If so, he's got to cut that shit out.
In my experience, peer review is more important here than methodology. In fact, methodology can afford to be rather sparse (and it should be for most circumstances) when peer review is relied upon.
Peer review is good because it helps good programmers become better programmers and at the same time, stops bad programmers from doing really stupid things. I think documentation is something that should be done, for the most part, after a project is close to completion.
For instance, we followed the standard procedure of design, then implementation, etc., etc.. Problem was that the people who did the design and implementation, weren't a part of the maintenience phase and all that design stuff was no where near how things were actually implemented.
It's really something that can't be avoided. Code tends to have a mind of it's own once it's written. There's a bit of a chaotic factor in it to where the slightest unforeseen bug in the most obscure case senario leads into a huge design problem.
Besides, it's alot easier to manage with a working product with poor documentation that it is to manage with a broken product, and acceptable documentation (or even good for that matter).
int func(int a);
func((b += 3, b));
If your company is affected by much turnover, then it's critical also to organize the boxes. For example, the first project of 1999 is numbered 99-1, the second 99-2, and so on. The archive shelves are ordered by project number. Put accounting in charge of keeping track of project numbers, as they already do...
What to avoid:
- each person responsible for keeping their own archives (no one remembers a year later if the guy who left did that....)
- lack of centralized storage (no one remembers three months later where the cd with the source code is or who had it last)
- depending on the client keeping the copy you send them. This is just stupid. They hired you for a reason, after all.
- depending on the weekly server backups. Those aren't project oriented, may or may not be around for a given week a year later, and can be hopeless to use if you're not sure what you're looking for and where it was.
Our company made some attempts to leverage work across projects. That usually didn't work so well. Each project, and each client, was just different enough. So you probably don't need everything from every project at your fingertips on the server all the time. The main goals for our archives was to be able to:- Prove it was client changes causing problems, as what we sent them worked, and we're happy to send it again.
- Pick up where we left off when a client comes back wanting changes in six months.
- Deal with a project that gets cut or goes on hold, and then comes back the next quarter with more money and wanting to "add it all back".
- Provide documentation for any change orders or contract disputes that may arise, during or after a project.
A good PM will archive at various stages, external and internal: every client delivery (alpha, beta, RC1, final), at end of design phase, when you've got a working prototype, etc.Good luck!
My favorite work montra is to "Document enough to put yourself out of a job". Meaning, write enough documentation so that anyone could walk in pick up where you left off.
I like HTML for documentation because...
- It's easy to work with and cross platform
- Access it from any machine on your intranet (or internet if your brave)
- Set up a standard documentation template to help keep everything uniform and to save time in creation
- Use a scripting language to automate creation
- Easy to convert to any other format
- Easy backups at one location
I would suggest treating your documentation situation like any other important project. Give it some attention, milestones, priority, manpower, etc. Start by documenting your documentation process!
See Zope fishbowl. It's a nice summary of a very lightweight process with some well-written thoughts on why such/any process is necessary.
As far as where to start, start with what you have. Most (not all) developers are happy to put their meeting notes, design docs, and such in a common/standard location and format (I recommend a text-based format in a revision control system) if one is simply designated. Someone whose technical ability they respect may have to remind some of the developers from time to time to put their docs in the designated place or to create a document from some important conversation.
Be careful not to attempt to switch from what you have now (nothing) to something unrealistic (full UML class and system diagrams, workflows, and state transition diagrams for every project). Be realistic and simply start to collect what you've got. Designate a spot for hard copy documentation and electronic documentation. Another easy first step is to designate a common format (ASCII, HTML, PDF, StarOffice, whatever).
Give that a few months to sink in. Then start to list common documents that should normally be associated with a project. Several separate "artifacts" of a project may include requirements, functional (user-visible functionality) design, detailed (class hierarchy and component interaction) design, implementation notes, decision log (bullet items of decisions made with date and those involved).
Remember: something is better than nothing. If each project simply has a decision log (Greg and Sheila decided not to support wizbang with a froznobit because it would cause all the tulips to wilt), then you have a start. Six months later, when someone asks, "Why didn't we use froznobits to implement wizbang? Maybe we should fix that," they'll have somewhere to look for the answer. The same can be said of requirements and functional design. Developers can usually figure out detailed design by long hours spent pouring over code. There's no way to divine what a program is *supposed* to do if there are no comments and no requirements and no functional design.
You touch on the fact that it isn't just docs, a key concept. I like to set up a Zope server and run Squishdot on it. I create 'topics' for each project. Evertime we do something of note, I make an entry, maybe put links in it, whole release notes and build reports. Now everything is indexed and searchable!
Underneath the Squishdot app I have a projects folder. Under it, 2 more, software and firmware. Under those, a folder for each project. In them I use a plugin called LocalFS which exposes a system forlder to the Zope environment. We put all our docs, spread sheets, gantt charts and any other project artifact. Another page does an SQL query against our bug database and displays that kind of stuff.
I can also pull in headlines via RSS to make the site more interesting and usefull. I even use Radio Userland at home to create a custom RSS feed tailored to our specifics needs.
The last thing is to instill the culture, this takes time and patience.
If documentation is short, it's useless. If it's complete and accurate you'll never have time to find which page of the 35 volume set you want to read.
Write good code and pray.
Need Mercedes parts ?
I tend to write comments about why a particular API was designed that way and what limitations (be it time or requirements) result from that choice. The main reason I do this is when I have to go back to extend it, I have a note to myself about how to extend or fix it. Murphy's law says the feature you think won't be needed will be the first one requested.
The language isn't slow, expensive, or embarrassing. Like any language, it's only as good as the developer that writes it. Unfortunately, since CF is so easy to learn, there tends to be more novice code out there you'd typically find in other languages (hence the bad rap). No fault of your own, you seem to have some misunderstandings as to how CF works (for example, CFScript was never, never meant to replace compiled objects). From the sounds of it, CF isn't your primary language - however, I work in CF every day (I'm actually on the board of a CFUG and have contributed to a couple of CF books) so naturally, my perspective differs from yours.
The best thing about a boolean is even if you are wrong, you are only off by a bit.
what about all those diagrams and handwritten notes. If not, do you store things in a folder per project, and how do you then stop documentation from getting lost and making sure people store things where they should.
Try hiring a secretary. Organizing and keeping track of documents is centuries-old technology already.
And good luck. You've just admitted that your organization doesn't have even the most basic organizational skill between the lot of you.
Whatever you do, don't write any documents at this time. Instead put everyone (if possible) in one big room, with pens and whiteboards along all the walls. Supply lots of coffee, food, snacks and soft drinks.
Let them hash out all the details of what you believe the customer wants. If you have a real customer available, chain him to a table in that room and don't let him go until you're satisfied.
Write down user stories on post-it notes, stick them to the walls, sketch UI designs and user interactions on the whiteboards. Don't worry about documentation! What matters is that you all have the same vision and understanding of what to do.
Documentation on paper is just about the worst medium possible for transferring information from one person to another. It is one way, it is low bandwidth, it is not visual (unless you have lots of pictures and such). It basically sucks. Two or more persons by a whiteboard is the best possible technology for information transafer. The ultimate solution is if you have a printing whiteboard, which can give you a hard copy of what you just jotted down.
The real documentation, on paper or on the web, can come much later, when things have stabilized a bit. In the end it may never be needed, in case your project is cancelled.
All these tips comes straight from the book Agile Software Development, by Alistair Cockburn. The best SW related book I've read in years!
Mats
well we created our own custom Documentation System which basically is a bunch of XML Tags embeded into our code and a PRogram that crawls thru the Code files creting descriptions of functions etc on the fly. I works flawlessly and is at the same time available in our development intra under the project name . All you have to do when you make a dchange, is write inthe codefile the comments to ir and run the update script on the file, it then updates the online documentation on the fly and the new things are available.
total development time for this was 3 months and had 1 guy dedicated to developing it. We then made it so that everyone was "excused" from projects for one week where he/she went thru the code of a project that she worked on (or more) adding the comments to functions.
We have now over 1 GB in documentation and new employees grasp the coding principles VERY fast.
Anyway thought i put my 2 Cents
PS: we have 60 people working in our Company and only 20 coders. But the documentation applies to all including us in the IT Department.. and with the scripts its VERY easy...
//Vic--- from Finland