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?
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
Then refine this.
It's a fairly painless process, and you can do it in teams.
Of course, the big step will come when you need to get someone to update and maintain what you've created.
Sig: What Happened To The Censorware Project (censorware.org)
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.
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?
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.
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.
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
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.
-ryanDocumentation takes a lot of time. Perhaps up to as much as half of your development time, especially in the initial stages. Plan for this extra time.
Having a record of what you did to get to the point you're at is INVALUABLE in saving time later on: a process that takes 4 hours (including documentation) may take only 1 hour the second time, IF you have proper documentation, 3 hours if you don't.
Give me my freedom, and I'll take care of my own security, thank you.
This may sound trite, but documentation is there to document your actions, plans and outcomes. I don't think it really matters how you organise your documentation so long as you can get it back again later without too much hassle.
I suggest having templates for all the major areas you would need to have documented - or at least identify the things you want documented and make sure everyone does their part. Things like proposals, project charter, agendas, minutes, functional specs, design documents, project plans, change requests, test cases, test plans, etc.
Obviously, this all ties in with project management and your methodology of choice. If you don't go out and get a consultant to guide you, at least read a few books and get some ideas.
I'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
Seems easy enough to keep your documentation in the same place as your source code. You do have source code managment right? If not, you should start there. [sourcesafe,cvs]
Documentation can be written in whatever format you want, but a standard which is compatible with your management systems change log tracker is a good idea.
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...
It's the medium of choice for many very complex applications and scales nicely (think the WWW). Overall, it's going to be disorganized, but very organized as far as the document structure.
Depending on what type of software your company writes or is producing documentation for (I'm guessing web applications), the structure of the document would be tailored for this, with appropriate entries for functions, global variables, and document constructs.
What's good about this is you can turn HTML into anything any language, and if you write it right you can show it through just about any device. Later on, you might want to package windows help files with your shipping product for your client -- HTML would work well for that. Well, HTML would be much better than any custom or home-brew solution you could come up with.
I would start by looking at what other projects have done. Which project's docs are easy for you to understand and progress through? Copy them. Start with a good synopsis for your own, introduction, and begin planning your document structure. What you will probably find is that your documentation is going to look like (or should look like) your source tree.
"I'll just chip in a bit for RedHat: I actually have that installed on my university machine." - Linus, '95
Documentation wasn't invented by some lunatic who liked to file things. I have seen many projects and organizations who were failing because they lacked documentation. The key, I think, is to keep the ultimate goal in mind. Don't generate documentation simply because that's the way it is "supposed to be done". If it will help you, then do it. If it is interfering with actually building the product, then don't do it.
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.
There are many systems of documentation that do this, Java wasn't the first.
I like doxygen, myself.
How about rephrase that and when to start...
/// that provides printable documentation, similar to javadoc. (But who cares about that) Unfortunately if you look at some of my in-line documentation you find stuff like:
RIGHT NOW
Or suffer our fate...
There will be a time were you will absolutely have to start documenting your products, how-tos, specifications, deliverables, whatever. Finally when you realize you have to do it NOW... you'll look at all the work you have to do, and nobody likes to write. The best thing to do right away is, if you have the money, is to hire a technical writer. Then have him or her write, that's what they do all day.
Then you can worry about problems like versioning or storing the documents, whether storing them in the DB or in your CVS (I guess that is considered some form of database).
One thing to bring up is there is a lot of great ways to document these days within your code. Javadoc is a great utility if you want your coders to start documenting their own stuff, learning javadoc is easy, but doing it is a pain in the ass. I think Microsoft in their Visual Studio.NET is introducing the
/**
* @author Me!
* It's 2:00 in the morning, I'm tired and drunk
* the following ain't pretty but it works for some reason
*/
"It takes many nails to build a crib, but one screw to fill it."
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
First you must decide what you are documenting.
Are you documenting:
These three items have radically different approaches.
The first, item, "The Process" has its own sub-itmes. Is it to get someone acquainted with the program. Is it used to help manage its growth?
The second item too (pun intended) has a couple of sub-items. Is it to keep functions from overlapping? Is it to show what each one does once the user already knows that this is the function to use.
The third item also can be divided into sub-items reflecting on who needs to read it.
The approach for documentation is first to decide what *exactly* you are documenting, and then, who is it being documented for. Between these two details, you can decided on the approach, and the tools.
Deciding where to store the documentation would be where everyone could get to it. Storing it ina database and displaying on an intranet sounds like an excellent idea.
Have you read my journal today?
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
Any large bookstore will have tons of books on various methodologies. Software developers fight religious wars over them. I think it is best to hire an experienced person who has worked with a methodology, rather try from a book.
Some more popular ones:
First is the one coming out of MicroSoft called SOLID. MicroSoft software development was pretty disorganized in the 1980s, but improved considerably in the 1990s. Love them or hate them, they manage to get a fair number of winners out now. You should know their methodology.
A very popular "counter culture" slashdot-type methodology is Xtreme Programming. Emphasizes small groups, pair-programming, incremental project goals, e.g. shippable software every 2-4 weeks.
And then there are the tools, for handling pieces of the projects. UML for capturing the objectness of a system. Source control for software versions. Nightly builds and automatic tests. Project Timeline Planners. VERY, VERY USEFUL is the bug/enhancement multi-user database. It ties together managers, developers, testers, and customers. It gives a measurment as to whether more bugs or fixes are being generated at given pahse of a project.
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?
I'm in pretty much the exact same situation. Except ASP instead of CF (sorry /. crowd).
We've got about 15 people here, and generally, the way we do it, it we have project specific production folders on the network, and those folder get backed up at important points in time (delivery, every month, depends on the project and it's timeline). Thos CD's are stored in categorized drawer, which has an accompying spreadsheet available to everyone on the network. This spreadsheet is (or should) be updated every time a cd is put in the drawer. Most workstations have a cdr built in, plus we have a machine for just burning cd's, plus a USB drive for those unfortunate who don't have an internal, and too lazy to go into the other room.
We also have a paper system, where all relevant materials, such as proposals, vital emails, as well as hand written stuff, goes into hanging file folders in a file cabinet. 3 months after final work is done on a project, the folder gets archived to the basement where we do all our file storage.
And of course, the gratuitous entire nightly netowrk backup, which is kept off site, in case any of those cd's ended up kaput.
It works for us, like I said 15 (which is generally our max, last summer we were down to 7) production employees, including programmers, designers, QA, and project managers (that list isn't exclusive, most of us where a few hats).
Th
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!
Make sure that everthing you code is in modules/objects/etc.
Then, as people code they enter data about how the modules and interfaces behave into a database.
Everyone gets to add info about the modules, no one can remove it. You are building a database of knowledge about your work.
Modules in the database have extra fields to identify functionality, connections, general areas.
You can then run reports which become the basis for chapters, etc.
Of course there are plenty of decent programs for this sort of thing, complete with version control, etc. In fact you could use any common coding version control program, storing basic text instead of code. Run it in side by side with the code. then export to a text file for reformatting, etc. just keep style, etc consistant.
"It is a greater offense to steal men's labor, than their clothes"
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 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!
...is such a convenient way to avoid facing your problems!
You can actually use the javadoc tool that comes with the JDK to spit out html documentation on any language, it basically just looks at your functions. I've seen it done on C code and works nicely
[alk]
for (itemIterator=0; itemIterator < itemMax; itemIterator++)
itemPointer[itemIterator].isFlagged = 1;
... then I really don't want anything to do with you. There are good and valid places to use i, j, retval and friends. There's a rule of thumb about the length of a variable's name being proportional to the logarithm of the scope (measured, for instance, by the number of lines of code it can be accessed from).
--grendel drago
Laws do not persuade just because they threaten. --Seneca
we have no idea where to start.
"The "
I am anarch of all I survey.
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.
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...
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 ?
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.
We used to have the same problem when I joined my current project in 1999 (yep, 4 versions later, we're still doing the same product). We are using Lotus Notes (no choice), which has serious drawbacks (no Linux client, buggy SMTP, weird shortcomings, very bad help, crashes at odd times) but happens to work very well as a collaborative environment. I suggest you get a good collaborative environment that allows its users to:
Then create one or several databases containing "how-to" documents. For instance, I see a few popular documents here: how to reload our DB tables, how to set debugging options of a certain product, how to configure SSL for our web server...
We have one of these little document for each procedure that has to be done several times. One-off tasks are not documented. There is a strong incentive to document a procedure when you've been asked to perform it several times.
Random papers and drawings are scanned, but their use is discouraged in favor of editable files.
Mostly, whatever collaborative system you use, train people to use it and provide incentive for its use.
And don't think it will be free. It will start saving money after several months, not next week.
--
Mad science! Robots! Underwear! Cute girls! Full comic online! http://www.girlgeniusonline.com/
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;
You use ColdFusion. This language is a mess -- it's slow, expensive and embarassing to work with. It's also very easy to understand, which is why it's well worth the cost, sloth, and total lack of knowledgable people.
I came into a codebase of about 5000 cf pages. Only two of the original developers are still with my company. There is no documentation and these were not good programmers -- my portion of the application was by and large coded offsite by amateurs. And at the same time, I have never really been halted in my work by the unavailability of documentation. Hindered, maybe -- slowed a bit, especially during a set of endless includes. But never halted.
ColdFusion is a mess to program complex things in. Cfscript is apocryphal and best replaced by simple COM and Java modules that do the same thing faster and in a much more understandable fashion. What you're left with is a base of very simple, readable code that's actually spoiled by documentation. (those <!--- tags are murder)
Oh yeah: name your variables wisely. That's the key to ColdFusion
Hey freaks: now you're ju
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
The problem with your approach is that the bare minimum quality works in the short run, but it's very difficult to get out from under that hole once you create it.
Also, you assume that moving as quickly as possible is the polar opposite of moving forward with a process in place. My counter to that is that a good process can actually save you time, even in the short run.
I've been at places where everyone is in such a hurry to move fast, to get product out the door, that they had to do the same things over and over again because of duplication of effort, mistaken assumptions, and so on.
Hell, look inside 90% of the burnt-out hulks of once world-beating dot-com companies in the Valley and you'll hear the same tale over and over again - "we were in such a rush, nobody knew what was going on, when the senior developer left, we had to redo everything from scratch.." etc. This isn't just hearsay - I've seen it first-hand.
I'm not trying to argue with you, but just ponder that the choices might be less binary than you present them. There is a middle ground between complete failure and moving as quickly as possible with the bare minimum of quality.
Read the EFF's Fair Use FAQ
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
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
You're just jealous that someone using ColdFusion can do something in half the time it would take using PHP.
In my opinion, someone that knows his language well and has developed a decent library will do things faster no matter what the language.
Seriously, because it's "closed source" it's bad?
I never said it was bad, it's just not as applicable to the majority of the readers.
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.
Not a good analogy. You are comparing one closed source system that costs money with another.
[snip sales pitch for Cold Fusion]
Perhaps you're just scared that someone without a CS degree could take your job using ColdFusion?
Someone without a CS degree will never be in demand as someone with one. There are many basic algorithms that apply to any language you choose. Where businesses use self-taught programmers, we tend to get paid even more to clean up afterwards.
Phillip.
Property for sale in Nice, France
Perl has POD, which can be embedded in your source in a manner similar to javadoc. You can then use standard Perl tools to turn the source into html, LaTeX, man pages or whatever.
GROGGS: alive and well and living in
The main problems are:
To solve this, i propose a novel approach:
Video Tape everything
Record:
- Brainstorming sessions
- Developers describing their code (highlighting it, showing it on screen, explaining what it does)
- Building and integrating activites
- Everything else you can remember
Seems like a weird thing, but try it. When you document, having the tapes around is a precious resource.free the mallocs!
I joined a company about a year ago; they'd spent several million dollars on getting a website built by a big consulting firm, using a cutting edge content management system. "Is there any documentation ?" I asked, on my first day, and the project manager from the consulting firm proudly pointed at the shared drive with nearly a gigabyte's worth of stuff in the "Documentation" folder.
I poked around - weeding out the huge screenshots and photoshop files the designers had created - and tried to find out how the system worked; I found a folder called "architecture", and started to read. Funny thing was, most of the documents were more than 6 months old; several were more than a year old. Hardly any were written by current project members. There was no road map, no versioning. In short - the documentation - though plentiful - was badly out of date, often actively misleading, and totally pointless without the writer to explain the context and intent.
This is not an uncommon occurence; there are people with (parts of) the answer.
Check out "Agile Development" by Alastair Cockburn; he has very strong ideas on the topic of documentation and how to keep it relevant.
Next, buy "Code complete" by Steve McConnell, and make sure everyone in your development team reads it and understands it.
You might also want to check out the ideas behind Xtreme programming - it sounds to me like you're starting to find it impossible to maintain code written by other people with different coding styles and are hoping that documentation will save your bacon....it won't.
Most long-term projects rely on coding standards, a common vision and understanding of the architecture, effective communication and well-written code. Documentation is usually done because the customer insists on it, or the management team believe it's going to solve hand over problems. It rarely helps the development team to get to grips with what is really going on...
Where's the documentation for the linux kernel ?
It's all very well in practice, but it will never work in theory.
You need to start documenting today. when you make a change, document the area you change, how it works, why it works that way, gotchas that you had to watch out for...
I started doing that 3 years ago for code that I maintain, and I'm getting close to done. Often I go back to something I documented before and update it with knowledge I discovered latter that makes things clearer. I also discovered I maintain one module that is as close to perfect code as I've ever seen. I know that because I have not done any documentation on it which means nobody has found a bug, or a situation it doesn't handle already.
Unfortunatly I've also discovered some things that I don't know how to document in a way that others will know what to do when it happens again. In my case hardware designed a new board that required different registers. We had to compile some things differently for that board, and to make our makefiles do that is really easy once you understand how they are generated, but difficult if you do it the obvious way. A simple change once I found it, but I don't know how to tell others so they will figgure out where to make the change.
In any case, once you get some documentation it can be orginized. Thats not something I do well. I don't write documentation well either, but at least I write it, and that has helped.
Small company here (~20 ppl), and we keep notes on various projects in a custom application that we wrote with a database backend that allows us to write notes on projects, track time spent on projects, and run reports.
Another major part of our arsenal is a CYA box. (Cover Your Ass) This is a box or other container into which all notes, drawings, printouts, scratchings, post-its, code scraps, etc....EVERYTHING goes. Why?
Two reasons:
- It allows us to show a paper trail of our development. If you ever get sued for copyright or patent infringement, you'll be glad you had this. It shows, in order, how the application was developed. Since everything in the box is layered in chronological order, this works well (First item in is oldest, last item in is newest). We seal boxes up when they get full, date them with the start and end date and mark a destroy date on them (7 years hence, usually).
- Ever delete something you wished you hadn't? Had a HD crash and wipe out some of a program? Then a CYA box is a handy thing. I haven't had to use it very often, but trust me, restoring programming code from paper is better than nothing. (tape or CD is better, but it's a last-resort backup)
Whatever you do, document EVERYTHING. If you sneeze on a project, document it. Documentation is one of those evils...if you don't do it, you'll be fast but you'll kill yourself later, and if you do it too much you'll slow down product. But it's worth the extra effort.Blog,Twitter
I was recently looking through the source code to pysol and it was like that. Anyone who has problems writing good documentation, or wants to see just how good it can be should check it out. I've been coding for about 14 years now, and pysol took the cake. But then again, I'm one of the people who doesn't comment anything.
The Outreach Project Tool is superb. Easy to install, easy to use, and has a very slick professional feel. It wouldn't look out of place in any top corporate environment and I consider it to be a shining model that Open Source software standards should aim for. By "dependant on LAMP" he means "Linux Apache MySQL and PHP".
Phillip.
Property for sale in Nice, France
Doc writers will use the tapes in order to assist them in writing the documents for the project.
free the mallocs!
I'm not a big fan of Perl, but the way it manages all these little state-keeping variables is something you have to admire. Many of them have standard names, and are referenced by default in most contexts.