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""
I know that the KDE team uses DocBook,
:: All Day Long. All Day Strong.
for which there's a great guide (crash course)
that they encourage their writers to use.
m o n o l i n u x
in java you just comment the functions in a certain way, and it will build the documentation for you.
maybe you could design something similar, and then use your new program to document itself!
MARIJUANA, SHROOMS, X: ONLINE?! - E
TWiki, a flexible, powerful, and easy to use Web-based collaboration platform has worked well for us.
http://twiki.org/
Far too many companies approach tech writing as the "music department" of the company: Nice to have, but not really necessary. The problem is that the lack of attention given to quality documentation winds up costing the company later. If you don't know where to find such a consultant, you could always shoot off an e-mail to a highly qualified individual such as myself. *smirk*
Got Rhinos?
what about all those diagrams and handwritten notes.
When I worked for Intel Software Testing (hence the nick) we used Visual Source Safe. It allowed us to store any kind of document in it (source, jpg, vsd, mpp, etc). With the check-in/check-out feature and version history it allowed us great flexibility and reduced wasted time figuring out who changed what.
I know it's a M$ product, but it did the job for us.
ASCII tastes bad dude.
Binary it is then.
From the what you said with different people and different or no methodologies there is a lot that needs to be done. First off, standards:
- Literate Programing: What you write, should make sence. Variables such as a, b, c, thing, object, stuff, crap etc should not be allowed. A new programmer should be able to come into your shop, read the code and it should make sense.
- Commenting: All source should be commented. That doesn't mean that hlaf your source files should be comments, but anything that doesns't make sense by simply reading the code needs to be commented. At a bare minimum, the person who wrote the code should have there name in there
;)
- Source Control: Please tell me you have CVS or something like that setup. If not, set it up
- Testing: Test early and test often. When your done with that, test again.
;) You might want to investigate Extreme Programming. This will help quite a bit to launch good solid projects, on time.
- Standard Design Methods: It will help you out quite a bit to have standard design methodologies. Standard patterns to follow and ways of doing things will help you quite a bit.
Secondly, make sure you have a forum for you developers to work together. Setup an IRC channel or something, just make sure you have a place to chat and share experiances / bugsThose few things should get you started. They don't totally address the commenting issues, but I would say that is the least of your problems... I could be reading way to much between the lines. Just my two cents.
-ryanI've used, successfully, two systems. SourceControl is standard way of doing it. Basically, treat it like a shared filesystem. You have to be very careful about the structure or things tend to get lost. Also, it becomes very easy to make duplicate docs when one gets lost.
I found it easier to use Twiki (which is a WikiWeb-like project). Twiki has built-in version tracking, can store any kind of information, including meta-data, and has pretty advanced search features. We've just started using it at my new company, but I really like it so far.
The only thing Twiki is lacking is proper authorization. Anyone can go in and write over my docs. Of course, it logs that change wit the user's name, so there are decent forensics. Still, I'd rather not have these hassles than be able to track the perpertrator down.
Citizens Against Plate Tectonics
1. Code level documentation. Having good code-level comments is vey important for figuring out the nuts and bolts of how things work. Well commented and well structured code can make or break a long term project. The important thing is to keep the comments up to date so that you aren't providing misleading information. This is easy to do, however. All it takes is a little dicipline.
2. Process and Design Documents. There are many ways to handle these, but one simple way to do it is to create a development "Intranet" and keep all of your developer docs in HTML format. HTML documents are easy to create, easy to organize with hyperlinks, and easy to view. Keep a copy of your HTML documents in CVS or some other version control tool. That way you can have a record of your changes.
Code level docs are pretty easy to get started. If you have a good development team, you probably already have your code well organized. If not, assign pieces of your project to different programmers and have them document their assigned code.
Design and Process docs can be handled the same way. Make a list of things that you need to document (ex: build instructions, class hierarchies, etc) and assign these out to programmers.
The key to any documentation system is to keep things up to date. The best protocol is to have people make changes to the docs as they change the system, or as they discover bugs in the docs. Treat your docs just like you would source code. Strive for "bug free" docs. If you can't make a change to a document for whatever reason, log it as a bug so the change doesn't fall through the cracks.
Once people get used to treating docs as code, they will keep them up to date. If people have the attitude of "I'll document it when I have the chance" your system is doomed to fail.
Good luck!
------
www.moneybythenumbers.com
We started using a wiki about a month ago and we love it! We named it "The Brain" and it "keeps getting smarter". Highly recommended.
Since you seem to be a cold fusion shop, try this out http://www.cdsi-solutions.com/cfwiki/ we had it running in about 2 minutes.
Ricky Silk
kung foo ezine let me waste your time.
There are many systems of documentation that do this, Java wasn't the first.
I like doxygen, myself.
From the look of most of these posts, there's not many software engineers out there. Sigh...
Documentation begins with a Functional Specification. It continues with one or more Design documents.
Without them, all you have is code that has comments. Not really useful, since no one actually updates their comments when they update the code.
The point of documentation is communication. That is, it enables people to work on different aspects of a project, at the same time, to a common goal. It also enables people to follow behind you and fix your bugs and modify the way the system works. They can only do this if they know what the system is supposed to do.
Thus, you *must* write a Functional Specification. You can't solve a problem that you can't define. That definition is the Functional Specification. If you can't write that, anything else you do is pointless.
Its actually worse than pointless, it just slows you down for no reason. The people coming behind you will have to throw your code away rather than fix it, because no one will be able to tell how it fits into the (undefined) big picture.
Look at it like this. Software engineering is a long term process. Its interested in the total life cycle of the system. Hacking is short term, interested in what's fun today. If you want to be a pro, you have to act like one...
Write things Once And Only Once
This means that whatever documentation you produce it should not duplicate information that can be inferred from reading the code. Documentation should only compliment your source. Describing algorithms in a Word document is a terrible idea as any duplicate information will get out of date. It's only a matter of time. Usually documentation should be more detailed around the user requirements and sparse around how the code works. Documentation is not an asset. It's a liability. Any new document introduced during the development process is an additional maintenance headache and a delay in project's completion. Always think twice before adding every single type of document into your development process.
Your pizza just the way you ought to have it.
A lot of people are posting saying basically "use system X to keep track of your documentation" or "use system Y to keep track of it" but are not addressing the main problem: it really doesn't matter how documentation is archived. Sure, CVS or DocBook have advantages over papers in a filing cabinet, but efficient access to documentation means nothing if the documentation itself is garbage.
/. crowd would have any trouble figuring out what a 200-line, uncommented module does when they have access to the complete and accurate specification, analysis, and design documentation. On the other hand, it's ridiculously easy to cause a regression fault nightmare when you are modifying a 200-line module with copious comments but without the detailed specification, analysis, and design of the product handy.
What documentation would I consider garbage? A lot of these replies suggest you use "literate programming" and "comments in the code", and while these are very useful to maintenance programmers they are nowhere near as important the specification, analysis, and design documents that should have been generated before implementation had begun. For example, I'm sure none of the
What you should be asking yourself:
1) For each of the projects we are currently working on, do we have the design documentation?
2) If 1, is the code we are writing completely consistent with the original design documentation?
if (1 == false), you are in BIG trouble. While development on a project such as that may go okay, maintenance will be a minor disaster area. It's unreasonable to expect maintenance programmers to maintain a project that's so poorly documented, and for such a small organization spending gobs of time hunting regression faults because the idiot down the hall made a change to a module that he didn't understand and that wasn't documented could be fatal.
if (1 == true) but (2 == false), you are still in trouble. Wrong documentation is orders of magnitude worse than no documentation, because what happens is that maintenance programmers don't realize that the code doesn't fit the specification and end up trashing half the project until someone finally catches the mistake.
My suggestion? If you have projects like #1 or #2, consider all the work you've done so far as a rapid prototype, trash all the code, and start from scratch with a reanalysis of the specifications. It might sound brutal, but you'll spend less cash in the long run doing a total overhaul now rather than waiting until later and letting it all catch up to you on the bill for maintenance.
If your projects are well-specified, analyzed, and designed, your employees already have the competence and the CASE tools they need to document their code well. Remember, the emphasis is on COMPLETE, COHERENT, CONSISTENT documentation; hell, even resort to printing your documentation on dead tree if you have to, as long as it's complete, coherent, and consistent it won't matter that much. Accuracy of documentation over efficiency of access.
-inq
My company had the same problem. We had dozens of little projects on the go at the same time, with lots of customers, and several outside contractors. How to coordinate, including across time zones, and with various documents to be shared?
So, being a software company, we wrote a tool! It's called Outreach Project Tool, and we've GPL'ed it. You can check it out at http://outreach.sourceforge.net, and download the source from http://sourceforge.net/projects/outreach/. Note it's dependent on LAMP.
Paul Gillingwater
MBA, CISSP, CISM