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""
Hire a new guy/girl...it's easier to saddle the new guy/girl with the crappy (but very important) jobs!
-Ben
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/
I always liked the record keeping as done in the biotech area... Every scientist has a lab notebook (offline) where references are made to everything that was done (and where things can be found).
:)
I'm always suspect of documentation and record keeping that is 100% digital. If the notebooks are witnessed and microfilmed, there will never be a question on when the work was done.
If notes about how things are done are kept on a notebook like that, it is a lot easier to go back and figure out what was done and how it was implemented when it comes time to writing real documentation. This does not address the inprogress documentation, but you should not forget about the tracking aspects. (CVS is good, but it could be falsified easier than a notebook I would think).
Don't get me wrong, I hate doing this... but it is a good idea
DrArt
-- Huh?
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
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?
are you documenting for users of the projects or are you documenting for present and future developers of the project? The two are completely different and have different requirements as such.
A web application by nature should almost always be self explanatory. A help link or button should be available prominently on every page. The better you do this part, the less it costs to support your app.
Developer documentation for a web app also works well with HTML. Not only can you use comments extensively, you can link variables and functions from where they are used to their actual definition. A common way to structure HTML documentation is to have a frame with the left frame containing a tree of links, an index, and a search. I would use something like ht://dig rather than a database to index your docs and allow searches.
No, Thursday's out. How about never - is never good for you?
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
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...
I say keep the oral tradition. Hire a master storyteller and have this person write lays and epics about the overwhelming odds and unimaginable challenges your programmers faced, and the way that these struggles between good and evil shaped the interface you see today.
Who wouldn't buy the support contract if it included a yearly visit from the master storyteller? By jove I believe I've just solved the "how to make money from GPL softare" problem...
:)
microsoftword.mp3 - it doesn't care that they're not words...
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.
It is very hard to make development people see this. Part of it is a real antipathy to the whole chore of producing documentation, even if your role is just to being interviewed by a tech writer and answering a lot of "stupid" questions I put "stupid" in quotes because it's the really stupid questions that your customers most need answering.
To be fair, the technical communication profession itself is a big part of the problem. There are a lot of "technical writers" out there who think an English degree, a little computer experience, and maybe a quickie certification course is all they need. Or recycled engineers whose prose style would make Bulwer-Lytton blush. There are companies where most or all of the writers are like this. Engineers find them a pain to deal with, and the docs they produce are mostly useless. Small wonder so many engineers think of technical documentation as a lost cause.
Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing.
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.
Assign each person to use a different word processor - e.g. Word95, Word97, Word2000, WP5.1, StarOffice, OpenOffice, etc.etc.
:(
This way you will know exactly who maintains the document - store all the files on the users hard drive , dont worry about backups - hard drives are very, very reliable these days and the damn server is usually always on the blink.
If someone needs to modify another document, they simply need to write notes on the old printed version and the document maintainer can update them later.
At least that's how it was in my last job
I'll think of a funny sig later on
Start with documenting the code first! Since the code is what must be
maintained in the long run, this is the critical place to make sure you have
decent documentation so any programmer can pick up where the last one left off.
Well documented code should contain as much comments (if not more) as
code.
Once the code is well commented, pull the comments out and use that as a
start for technical documentation, a reference to the design, functionality, and
interaction with other programs, modules, etc.
Once this is complete, then, and only then, should you start documenting the
programming project as a whole, mapping out database layouts, etc. (note: this
is from the standpoint that you did not do it correctly the first time and are
basically working from scratch). No matter what you use to document the system
in, it should be a common format between all projects and systems. Databases
should be documented using a decent data modeler, and don't forget to document
the stored procedures (in the procedures as well as external
documentation).
Once all the technical documentation is complete, then you should start
thinking about documenting the project from a user's point of view. If a system
works well and is easy to navigate, the users will rarely reference a help file.
I have walked into too many projects that were completed in haste, and looked
at way too much code that was not commented at all to know that had the previous
programmer done his/her job well, it would have saved me half the time trying to
understand why they had done something the way they did. When writing code it's
easy to assume that the code you write is blatantly obvious, but to someone not
knowing the system from the start, it won't be, keep that in mind and all your
code will end up being well commented, and writing documentation will be easier
later for anyone looking at the system.
In the future, remember that a well organized programming project will
involve much more planning and pre-documentation then actual coding.
http://www.codewolf.com - Just good stuff to waste time
You're just jealous that someone using ColdFusion can do something in half the time it would take using PHP.
Seriously, because it's "closed source" it's bad?
A good analogy would be Apple. Yes, Macs cost money, and OS X is not open source. But a Mac with OS X is far more elegant and easier to work with than a Windows PC.
Similarly, ColdFusion costs money and is closed source, but is easy for new people to understand, and incredibly powerful at the same time. It has a plain-english syntax that actually makes sense, and has tons of built in functionality that let you get work done, instead of chasing down some PHP component that you read on a message board might work if you can track down the guy who wrote it in some foreign country. It's backed by Macromedia, a real, permanent, profitable company that has tech support and a phone number.
Perhaps you're just scared that someone without a CS degree could take your job using ColdFusion?
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));
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.
My documentation lives in a vacuum. My tech manuals live in a Hoover, and my user manuals live in a Sears Craftsman Shop Vac. I guess you could say my documentation system sucks
Thank you, I'll be here all week.
XML causes global warming.
I didn't believe it but I was recently forced to use XSLT to generate unit testing code. So I read the XPath and XSLT specs (not long, easy reading) and thought I would document my personal library of C modules by defining the interfaces as XML and running an XSLT processor (Xalan-J) on it to generate an html reference, man pages, postscript, header files, etc. I'm still in the middle of it and trying to reduce the XML model but I have generated man pages and a very nice HTML reference. Here's an example. As you can see the style sheet isn't quite right. I'm working on it right now. If someone knows XSLT and wants to help, let me know...
The first thing you should do is create coding standards in which documentation is part of the coding process. The documentation standards should be such that you can automatically generate documentation as the code base changes.
For example, on every Perl project I work on these days, I introduce a script (about 30 lines of code) which auto-generates documentation from the PODs. The script can be run as a cron job that auto-updates the online documentation every week. That way, coders document as they go, and central documentation resource automatically regenerates itself on a regular basis.
The second thing you should do is set up an intranet site (behind the firewall!) for developer documentation. Include the auto-generated documentation, documents describing your coding standards, project management documentation for developers, use cases, class diagrams (does ColdFusion even have objects?), activity diagrams, sequence diagrams, etc., etc. If you have a team of 20 people, undoubtedly you have someone who manages code revisioning. Likewise, managing the developer intranet should be included in someone's job description, and, what's more, they should be given the time to do it properly.
Hope this helps
-- My choice of computing platform is a symbol of my individuality and belief in personal freedom.
Read The Mythical Man-Month by Frederick P. Brooks, Jr. (ISBN 0-201-83595-9). This is one of the best books I've ever read when it comes to managing any sort of software product - and it gives great advice, including a chapter on documentation and why it is so IMPORTANT.
Please, go out and buy it and read it - or check it out from your local library. It is a must for all programmers, even if you're not the one in charge.
Jake
Dating: while( 1 ){ call_girl(); get_rejected(); drink_40(); } return 0;
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
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
Hey can you imagine a Beowulf of these?
(He runneth for cover)
I say the future is a serious matter
And so for god's sake - hock and soda water!