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
We have a semi-customized document management system. He conducts real-time surveillance and documentation of our systems and files them according to the CNFS (CowboyNeal File System.) We've run into a few bugs with the eccentric cataloguing mechanisms (CowboyNeal's pockets) but otherwise it seems to run smoothly.
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?
WIKI is very informal and easy way to do
technical documentation.
One of Wiki implementations: http://www.twiki.org/
Go with a filing Cabinet and some notebook paper. Hire someone from Burger King to keep it organized.
Since you're a web development company, I'd suggest you set up a documentation intranet site.
With a little planning, you can make it easy for folks to figure out where to put their doc files and where to add a link.
If you want to go that far, you could also scan in handwritten notes and diagrams and post those to the site as well.
appended to the end of comments you post, 120 chars
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.
There's no documentation where none is to be found, and no documentation required where none is expected. If you do expect documentation, you have to write specific goals and outline them in a summarizing document that one of you becomes in charge with. With said documentation, you can now go about your buisness without that growing need for documentation which seemed to be your problem to start with. Damn I have a bad cold. Beers wouldn't help it, so I'm smoking something stronger than grass. I hope that what I wrote is still somewhat coherent.
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.
Docbook is the ideal solution to all ones documentation concerns... Using the Open Jade parser it is perfect for any open source project desiring to use only open source tools. It allows one to create HTML or POSTSCRIPT output. A single document can even be made from multiple files in different directories.
Try macromedia's sitespring. I've only skimmed over it but seems to do everyhitn oyu want
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.
CVS can be a pretty good option for text/html-based documentation. It can work for binary files too, but then you can't see diffs.
For hand-drawings, etc., you could always use a scanner, but I don't know how practical it would be. It would give you the ability to back stuff up in case of disaster.
Whatever you do, be consistent and be sure to document your documentation scheme.
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?
Save yourself a lot of grief and hire a technical writer.
If you have to do it yourself, look at some of the articles at www.raycomm.com and check the techwr-l mailing list archives there.
There are a lot of good technical writers, with experience with API and system documentation, as well as user docs, who are out of work right now. It shouldn't be hard to find somebody.
Regards
Keith
I just put things in a readme file. If it's going to be a big project instead of a text file I use html pages.
For instance one text file/ html change would be a list of versions & the changes that were made - another would be bugs/ future modifications etc
Video Game cheats, hints a
Do you have producers? They're the intermediary between the programmers and the clients. They interpret the clients desires, and we programmers implement those features.
They keep track of all the documentation.
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.
Transposed letters in the URL. This is the link for CVS.
Gee, software without much documentation. Who'd a thought that would ever happen?
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.
In my workplace we considered using MS Project to keep track of all our junk, however we came to the conclusion that we were too small a place for this.
Take a look at it and if you don't like walk away and never look back!
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.
I've yet to see a small company of your size successfully implement a full-blown documentation and project management system. Why expect a small company to act like a big one? Instead, find the top three frustrations and risks in your current processes and address them individually, rather than trying to put in place a system that's bigger than it needs to be. There will be time enough for that when the company grows.
Otherwise your people will be spending more time documentating what they're doing than they will spend actually doing it. Billable hours are key at that stage.
Working for a small (about 15 people) software company I found out the best way to take care of documentation is a combination of things.
First off, if you're using java, make sure you use javadoc code for every method and class you write (make sure that this is required by the company, we have code and documentation standards). If you're using any other language, still write comments for every function. Also, every bit of code which isn't very clear should have some comments to shed some light on it. And don't forget to add comments for every bugfix you did (at the start of each sourcefile you could make a small index of all changes that have been made, with the date of the change and the name of the person responsible for it).
Second, make sure that before you start to program, you have a detailed set of requirements and a well written project plan (design). This makes it easier to structure the program in a nice and tidy way which in turn makes it easier to document.
Third, always make a docs directory which includes all standard documentation, the before mentioned requirements and project plan, the notes from every meeting you have had, user manuals, etc.
Fourth, use CVS (or a similar system). This makes it very easy to document changes in your program (and also to find out what other people have been doing).
Five, for every project you're in, make sure a seperate mail alias is setup. In that way you can filter every mail from a certain project to a seperate folder, which is a nice way to keep track of things.
Other things you could do (which are not (yet) in use in our company but of which I heard) are setting up news groups for projects, setting up intranet sites for every project, etc.
Ofcourse, the methods I've described above are very effective when you start with a project. If there is a great need for documentation for already finished projects, you've been doing something wrong (one of my first lectures in software engineering was about documentation or, better, the lack there of). However, if you want to document those projects, I recommend you start with documenting the code. This is a hell of a job, but it is VERY useful (think about bug fixes and so forth). After that, try to describe how you've build up the product.
Ofcourse, these are only hints, but I've found them to be very effective in our company.
A trolling we will go, a trolling we will go...
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...
Slashdot has alread covered this here, and here. How on earth this is news for nerds I don't know, it's 1st year Software Engineering material (you mean you didn't ever study the subject? then why should we do your homework?). Insult to injury is that it's proprietry ColdFusion, not even a PHP project.
How this gets posted over the EuroLinux Alliance winning in Europe and defeating software patents, I'll never know (sure, mod me down offtopic).
Phillip.
Property for sale in Nice, France
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
Go wiki (http://c2.com). Learn patterns. Not only design patterns (hey, they won't hurt you) but also documentation patterns. Learn also about XP (okay, eXtreme Programming, not that Big Brother new Window) since its methodologies could apply.
More on that: CVS, docbook, XMI. CVS for code repository, docbook for generic document in XML (check oasis.org) and XMI for a standard for UML diagrams storage. These are the best options found in my case.
Supposing that you can make the effort. If not, I'm afraid that you will have to live with generic folders as code repository, Word documents and Rose files.
I was the manager of a development group. During the development process it wasn't too difficult to go through the necessary steps of requirements, design, etc. The company had a list of documents we had to write and have reviewed and everything progressed smoothly. (If you don't have a list of required documents and what should be in them you should definitely do that as a first step.) However, once coding started all bets were off. About all we were able to accomplish was user documentation and man pages (along with some testing and installatrion procedures) before the developer could declare themselves done. During implementation things change too fast and there is no motivation to go back and make old documentation current. The best thing you can do is to take steps to insure the code itself is maintainable as well as is possible (use code reviews, etc).
Have a meeting of minds and come up with a standard document template within which you expect defined *stuff* (tm) to be defined. Maybe begin with a brief 'This is what it does' paragraph. Give documents numbers so that they're referrable. Tell people to document before coding (hopefully). Follow software engineering principles (like the books tell you to). Define what the salespeople expect, then what you interpret that as, then let the programmers give their codal(tm) view of it, then let them define how what they're doing behaves in a manner to keep the salespeople/customers happy, then start actually doing stuff. Engineers are the master of cut-and-paste. They'll follow the templates until you modify them. I was a nubient non-documenter until my current job. I follow the templates. It works. Trust me.
Theres alot of customer service sofware that provide KNowlege bases. And your IT/HR dept can use it for bug/call tracking. You can store your documentation here. Its searchable and (based on what you get) easy to maintain.
thelikesofwhich.com
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.
zwiki, zope.
easy for everyone to add into.
Make it a rule that everyone has to use it, and document all the crap code they are making.
That comment really worries me. At the risk of sounding anal retentive, I'd like to point out that a total lack of programming methodology is, in my experience, a recipe for disaster.
Especially with a large group of developers. You will find it very difficult to build cohesive, useful documentation unless all the developers are at least in agreement on basic methodology to be used (code organization, division of scope, etc). You don't have to follow a college textbook but at least get some basic coding guidelines.
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.
Good code documentation flows, almost naturally, out of good code design & commenting.
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.
a majority of /.ers are open source types. have you read open source documentation? is this really the best focus group to ask about documentation? in fact i suggest you do what most /.ers do. wait till O'reilly releases a book on your project. :)
all in jest, folks.
-
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.
try reading How to write Usable User Documentation by Edmond Weiss. it gives an engineer view into writing documentation and at least allow you to focus on what type of documents and who they are for. on the other hand, some people would say that documentation is a waste of time with the time better spent making your product/system so user friendly that no documentation is needed and the systems engineering so self documemted that no systems doc. is needed.
Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing.
Unfortunatly their website (fusebox.org) is down but try fusebox. Its a self documenting, scalable methodology originally written for coldfusion but extended to other languages like php.
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
So instead of using a proven advanced version control system (CVS) with a wide choice of clients spread across many platforms, you used Visual SourceSafe (which screws up badly, I've used it)? Who said that "when all you have is a hammer, every problem starts to look like a nail"?
Phillip.
Property for sale in Nice, France
Get someone experienced who can lead you through the standard steps:
1. Figuring out what docs you need
2. Creation of standard boilerplates and templates for reusable objects.
3. Scripting to automate as much as possible
4. Establishing a data/document repository (at the least a standard consistent file structure.
Finally, if you want a custom document database so you can enter metadata and search for your files later, consider writing up something in PHP or Tcl running over mysql or postgresql.
You really need to know what your workflow is, what docs occur at each point along the way, then you build what's reusable. Make it as easy as possible but enforce it.
Don't scrimp on this.
There are many systems of documentation that do this, Java wasn't the first.
I like doxygen, myself.
Both FuseBox and FuseDoc are excellent tools/methodologies for Cold Fusion. This comment deserves to be seen.
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?
It's not terribly complex, but it does help when you have to pickup where someone else left off by making everyone code in a similar style.
Even if you decide not to use it, it incorporates some interesting ideas that might help you in other ways. (Organizing what the function of each page is, what variables are used, etc.)
You have a job?
Someone still invests in web startups?
Can you publish the contact info for the company investors? I have a few ideas I'd like to discuss.
Do it now. Don't wait for fancy doc support
tools. Do it plain html
you must. If' never wasted.
Do not repeat vendor information. Just doc
gotchas and give links to vendor info.
The primer gray Raleigh sky cheers the regulars within the alley behind Bob's Free Software Café, but not enough to draw them beyond the confines of their narrow world. The pecking order is clear as occasionally one of those nearest the steel drums, each containing a low fire, barks out a command to "pass up another bible", 'bible' being slang for the Linux books lying in tarp covered piles along the sides of the alley. On arrival, the bible is torn asunder and carefully fed into the perpetual fire. Fingerless old gloves type on invisible keyboards as the small knots of aimless alley residents talk to one another, forever modifying their favorite section of code. Laptops were once common but have long since passed through the local Open Source Pawn Shop to become just another fondly recalled and often mentioned memory for it's former owner.
The mumbling and air keyboarding is abruptly halted by a large steel door being thrust open, the doorframe filled by a huge biker entrusted with access control for the café. "Listen up", he cries, "send me in four guys with Wine experience, two with boot loader experience, and one of you stinkin' weenies with Gnome experience. And get a move on it." All heads at once turn towards the centermost steel drum.
One man speaks quietly, so quietly that even those who stand beside him must lean towards him to hear. Assignments are being given out. People will move into the café' based on this man's decision, new code will be added to the sacred scroll, new reputations could be made or old ones broken depending on what happens within the café, and only Linus can decide who enters the café'. Linus has retained his laptop, he's even managed to retain sufficient funds to live at the Y and ride the bus down to the alley each morning. Not everyone has fared so well. Most struggle to hold onto a good packing crate or drainage pipe for their home, much less ride a bus. Those who still retain a skateboard for their transport are considered wealthy, as are those who still own a backpack. All are former shareholders in Red Hat or other Linux companies, and all were faithful to the end, going down with their choice of Linux ships. The faithful had not so much as batted an eye the captains from the assorted Linux liners were rowed to waiting yachts by their faithful executives. Now, the faithful share their faith here in the alley and eschew opportunities outside of Linux as a tenant of the faith.
Linus decides, the word is passed through the crowd that the seven slots will be filled by six old timers and one "egg", a new guy no one knows much about. The old timers are near the door and line up, but the egg has to "pardon me" and "excuse me" his way through the mass of huddled hopefuls as he moves towards the door. It's some guy who once owned a whole ton of stock in Red Hat, something that's not supposed to make any difference. In his wake there's a lot of disgruntled chatter and an occasional complaint voiced loud enough to hear above the general murmur. "Hey, what's with the egg moving up so soon", someone finally shouts. Linus, obviously shocked as the challenge to his authority, slowly turns in the direction of the question. "You people know I make my decisions based on skills and skills alone. You all read the code. You all review it. You can see for yourself that this egg has made an important contribution. I don't like this type of insinuation and I don't expect to hear it again". He then turns back to the steel drum, bends over, and removes his laptop from his backpack. There will be no more comment from the crowd, Linus is coding, no one dares to interrupt Linus when he's coding.
By now, the egg has finally reached the doorway and falls in line behind the old-timers, the line is then allowed to pass through the doorway, the door promptly slammed behind the egg and a loud clack is heard as it's locked.
The café' interior is a stark contrast to the alley, something straight out of an old episode of "Miami Vice". The raised platform in the center is populated by several dozen obviously well heeled folk sitting before expensive flat panel displays, drinking gourmet coffee (the alley residents can still recognize that wonderful smell), snacking, and occasionally laughing, lost in the conversations piped into their hands free headsets, totally unconcerned with the grubby batch of Penguinistas who have just been shuffled in through the back door. Penguinistas called these people specialists, and specialists spent their time looking for arrangements and deals that made the PR people happy, the PR people being happiest when the deals resulted in PR adequate to sell shares of stock in the Café. At the rear of the café' are a half dozen old 386 machines with filthy keyboards and faltering monitors, all sitting on what appears to be countertop ripped out of an old kitchen somewhere. As a smiling guy with a Red Hat ball cap approaches, the mumbled name "Bob Young" passes down the disheveled line.
"I'm awfully glad to see you guys and would love to chat, but we need to hurry right along guys, OK?" as if anyone in the line would dare challenge Young on anything. "Now, you old-timers can each move over to a terminal, I'm sure you can look at what's on the screen and know which one you need to work at. You all know the code, right? Sure you do, so you'll know what section is your specialty and know what to work on. We'll have some Maxwell House sent right over, but remember, only one cup each". Young then turns to the egg, his grin gone, replaced by an almost bland stare. "Follow me", Young commanded before spinning on his heel and heading rapidly across the café. The egg follows young across the café to a steel door almost identical to the one he's entered through.
"OK, kid", Young said while unlocking a gray steel cabinet next to the door, "Linus says you're trustworthy, and you damn well better be". Withdrawing an envelope from the cabinet then quickly closing and locking it, he continued, "you take this CD over to the Y, the guy at the desk knows what to do, there's no need for you to open your mouth. Just hand it to him, wait until he hands you back an envelope, and then come straight back here. Knock three times on this door, then wait". The egg nodded, confused a bit by his assignment, wondering what was the goal, but then slapped back to reality as Young noticed his change of expression, with "don't fuck this up, egg. You do it right and you can do down the hall there on my right. Go ahead, look down the hallway to my right". The egg already had, he'd seen the lavish office chair sitting before a large flat panel display and already wondered what it was and why it was separated from everything else. "See it, don't you?" Young barked.
"Sure, I mean, yes sir Mr. Young, I see it", stammered the egg. "Well", replied Young, "if everything is kosher when you bring back the envelope, you haven't opened it, you get your ass right back here in a hurry and keep your mouth shut along the way, you can go down the hallway and fire up that new machine. It's got XP on it, any game you want, and the very best audio and video. You'll get three hours in there, just you, the machine, and your favorite game. No hassles, a full coffee pot, even a pack of smokes if you want them. Everything clear?" Yes, yes, it was all clear. He was going to get his fondest desire, a chance to play "Monster Truck Rally" years before it would ever be ported to Linux. God, could it ever get better than this.
"Wipe that stupid grin off your face, egg", whispered Young, "you want someone to notice you're thinking about something other than writing code for Linux? Now, I'll open the door and you hustle your ass off, egg, otherwise you're back out in the alley and just another egg fit only to pass out copies or Red Hat Linux in hopes of getting other eggs hooked". The egg fairly flew out the door, visions of Monster Truck Rally glowing in his head. He'd seen it on the Xbox, heard it had been put on the PC as well, but never actually tried it. Someone might have seen him in front of the Xbox at Wal-Mart where the game ran constantly for customers to try out, he'd never risk that. But now, a chance to actually play the game, this was even better than getting a chance to add to the code base. This was a chance to actually USE a computer just as if the main purpose of a computer was to let the user do what he wanted. You better believe he'd come straight back, he'd be back before Young could get the door locked if that was possible, thought the egg.
He tried to put all thought of the CD he was carrying out of his mind. He'd heard the lies about the Y running Windows, now he wasn't so sure they were lies. He wasn't sure at all in fact since inked on the outside of the envelope in bold letters was "MS W2k Corp Serv. Product Key" followed by a series of numbers. "At least", he thought, "Linux is still growing in the third world. Once it gets a solid base there, once the new versions and new drivers are all built, then it can come back stronger than ever. So what if a compromise is made here and there along the way in order to keep a prospective customer happy. It's not like someone is actually buying a legal copy of this Microsoft shit, it's more like keeping the money out of the hands of the evil empire any way you can. Young knows what he'd doing, he'll make a go of the Café then start that support thing back up". And with that, he ran on, focused only on getting back to the Café and firing up Rally.
Make sure your interface (both external and between internal modules) specs are clear, complete and up to date.
Everything else that has been said is important, but this is *the* critical thing. If you fsck up your interface definitions on a project larger than about 3-4 people, you either won't ship or will ship way too late.
What would Lemmy do?
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.
Ask yourself why you need documentation? And what are you documenting?
If your problem is unhappy customers because they product doesn't do what they expected, then your problem is in requirements.
If you're doing maintenance on throwaway prototypes, then documentation is the least of your worries. Actually, even if you're doing maintenance on existing (legacy) systems, then documentation is merely a nice-to-have. But if the code isn't self-evident, then in my experience, documentation doesn't help much.
You need to factor in a few things: (1) time to market, (2) effort & cost to develop, (3) lifetime/shelf-life of the system you're building, and (4) effort & cost to maintain those documents. If your company isn't going to be around in a year, or you're going to be switching jobs (either by choice or involuntarily), just grin and bear it. Others have before you... why be different?
You need an extra body. Software that collects documentation of so many different types (text, handwritten stuff, source, graphics) is cumbersome -- how could it not be?
File folders are these incredible paper-like modules that fit into drawers in cabinets. Get a file clerk and put him (or her) to work. He should have knowledge, or at least an inclination to learn about the type of work you're doing. This is a great place to hire a student!
Also maintain a shared network directory for each project. Let people go hog wild saving stuff in there.
Allow each of your projects to have a master electronic file, and a master file folder.
If you can't afford an extra employee, then delegate one of your programmers etc. to sit out on certain projects to act as the scribe.
It's really important that you keep detailed notes of what you do and why you did it the way you did. There's nothing worse than having to revisit a 3-year old project and having to restart from scratch. Don't you think somebody should be responsible for that??
Race car drivers need pit crews!
How well does CVS handle binaries these days?
If you need to be able to generate formal documentation, you should probably go for JavaDoc standard (that works well with almost any other language too). There are following reasons why to keep the documentation in the same place as the code:
Think of it. It should make sense.
Software should be free as in speech, but if we also get some free beer, all the better.
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
"Hardly used" will not fetch you a better price for your brain.
Have a look into Sitespring (http://www.macromedia.com/software/sitespring/). It is a web-based collaboration and file versioning system. It worked very well for a project that I was staffed on.
What you are thinking of is called javadoc. There are some tags used with html that create documentation. The downside is that if they are not java, I am not sure if other languages have such a feature.
One thing that I would stress is creating standards for your developer's comments/headers/documents. Creating templates is extremely useful. I hate coming into a project and you start looking at other people's code to see that EVERYONE has set up their own standard for commenting their code and documenting their functions. Inconsistency creates a steeper learning curve for new people coming into the project.
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...
Ideally you want to have a system that is a mixture between document management, collaboration and knowledge management. Take a look at the products from Entopia. http://www.entopia.com
Word (or whatever for all you anti-M$ freaks) documents to start. There is a program called Visio that we use at work. It is a neat program that helps with flow-charts.
We also use something called PVCS Version Manager and PVCS Tracker. Version manager is just that (there are other, even free, version managers). It allows for code versioning. You can also use it to version changing documentation.
PVCS Tracker is a system of keeping track of open "issues". If there is an enhancement/bug fix/whatever, you just open a ticket, and close it when it is done. You can also assign owners to the tickets, as well as a progress label. So when the coding is done, you can change to "testing" and the person responsible for that would then take over...
I'm not a PVCS advocate or anything, it's just what we use...company wide.
I think the MAIN thing to do is to start doing something. If you START documenting, you will, over time, refine your documentation process. There will be mistakes, but just keep improving and working on them...
A modern day witchhunt.
Regarding individual technologies for document storage, pick one. CVS works fine; if you have the money, Designer is loads of fun to play with. ;)
Two other things. Idealy, much of the documentation should be done before coding starts. Also, the programmers shouldn't be the only ones writing docs.
Good luck!
We have a database created in lotus notes, send email me and i will send you some examples.
Basically things are divided up into a few areas, there is a changelog for each program (all cookie cuter with different names)
and a Service Request log to show the needs for change and who is working on what
for example, a request is entered in to the SR database to change a program to jump throu hoop b instead of A that document is closed when it is done and a log is put into the other database saying
date xyz changed blah to dlah see SR a3207zm$rulZ!
this has helped us stream line our work flow!
notes rulz!
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!
Couldn't have said it better myself.
You know what?
1. Come up with a inline code documentation standard (for the files themselves) and a general standard (for any other supplementary files).
2. As I assume you are coding right now, only edit those files you are currently working on and on all future files via your standard.
3. When time permits (or when you re-edit old code), document your old files.
4. Tweak documentation with every change.
This was is an easy incremental way of getting around to document everything without resorting to a big system.
What is music when you despise all sound?
I work for a small economic consulting firm as a systems administrator. Our company receives all types of documentation everyday from all of our clients, and we create many, many reports ourselves. What I did was write a small application that lets you check scanned documents into a MySQL database, and then runs through newly scanned documents using some OCR software (I can't remember what the name of it is...I did it a while back) to create an index of keywords that you can (slowly) search on. I did this because there is software called Hummingbird that works really well, but costs an ASSLOAD of money (in the tens-of-thousands range). It took me about three weeks on and off to write, but you could probably hire some intern to do what I did for a summer project for pretty cheap. Our server that we put together for the document repository has an 80gig hard drive, a 1.4 GH AMD processor, and has worked just fine for us so far.
Since you specifically mention ColdFusion as the development target, make sure you take a look at Fusedocs, a part of the Fusebox development methodology. Fusedocs are similar to Javadoc -- it is a way to self-document ColdFusion code in an XML format which can then be turned into more formal documentation.
You also owe it to yourself to check out Hal Helms website where he has tools for Fusedocs (including CF Studio VTML plugins) as well as the related wireframing and DevNotes tools -- both of which are extremely useful.
I've been doing CF for nearly 5 years and Fusebox, particularly the new Fusebox 3, is a useful design/development methodology as well as framework for building CF apps. Plus its all free/open-source/community-based/etc.
ZOPE, http://www.zope.org/ with its Content Management Framework http://cmf.zope.org/ and Plone skin http://plone.org/ work as an excellent out-of-the-box intranet style system.
you can catagorize documentation (it also has a search engine, so you can use the search box to search any of your documentation. but even more importantly.. you can easily assign keywords to documents.
Wiki works well for engineers. but not really that well for designers. but designers work mainly in images, so keywords would work just fine.
everyone will need to come up with a convention and load as much data into the system. if people dont use the system - its useless. so 1) technology piece, 2) commitment piece, 3) integrating it into other facets of information systems.
I think ZOPE is ideal for managing documentation. you get some primitive version -- but on a whole it works *really* well.
I'm going to get modded as flamebait but...
Buy a book or something, there's good structured ways on how to engineer software...
Next on ask slashdot
"I want to build a house... I bought a bunch of wood and stuff, but I don't know if I should pour cement or cut the grass first. What do you all think?"
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"
cluelessnewbie writes: "I have no idea how to run a business. Can you please tell me for free. Also, what is Linux, and will it write a business plan for me?"
No comment at this time
With it you don't even _need_ to write documentation or design artifacts. It's assumed that all the documentation you need is in the heads of the programmers and the on-site client.
YAY XP!!
(But wait a sec.... what if one of the programmers leaves the project... OH MY GOD!!!)
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.
Being a CF programmer for several years (and hopefully I'll be a Technical Editor for an upcoming ColdFusion book), Fusebox is certainly the way to go in combination with a Source Control product. Ironically a lot of the changes I made for myself when using Fuse2 are incorporated into Fusebox 3.0, so I think I'll probably use it exclusively on my next project rather than the hybrid version of Fuse2 I've been using.
I've only used MS SourceSafe with CF projects, but I'm currently getting curious about playing with CVS & CF Studio.
Fusebox.org is down right now, but you can learn more about it at Hal Helms website in the meantime.
...anyone afraid of 'the right way' lacks discipline. Best to ignore such people.
ColdFusion programmers? Typing a few cfquery tags doesn't make one a programmer, you know...
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!
documentation are for wimps
I figure I will probably be flamed for this, such is life.
I worked in a company with web developers, sales people, coders and more.
We had PC's, Macs, Linux, and everyone had different ideas about what package to use for documenting (from word to vim).
The key mechanisms you want out of a doument management system are:
* Store documentation in a standardised format.
* Use a Versioning system which will track users and differences between versions.
* Ensure that the data you put into the versioning system comes out in the same format.
If possible try and get everyone using Linux, or tools compatable with Linux. However you might be like us and not have the power to wean the rest of the company off microsoft.
In that case, you can go entirely commercial (Rational have some nice stuff for version managment) or try the following.
Use CVS as the version managment system.
Store your docs in either html, , sgml, xml, or txt.
For HTML there are plenty of editors in numerous plaforms.
Have a look at the Linux Documentation Project for SGML editors.
It is possible to convert word documents from:
Word->rtf->xml or html-> put into CVS (and then go back again.
This does require management at the word end to ensure diagrams are referenced outside the word document rather than imported in. (Check the import options in word).
Word docs can be stored in CVS, but they need to be stored in binary format, consequently you cannot see the differece between them by doing a "cvs diff".
Unfortunately, using word docs means that the linux guys are forced to read them - yes, there are ways, but it is a righ pain in the arse.
Not everyone comes from the same background of experiences as you. That does not make them inferior or wrong, it only means they come at things from a different viewpoint. Knowledge is not just information, it is the exchange of ideas. Without the exchange of ideas there can be no real knowledge or innovation. True innovation has never come from doing things the same way, but from doing things differently. Slashdot seems like the perfect place to exchange ideas and experiences and perhaps, each of us can learn something.
So what's your problem, hemmoroids acting up again?
For USD50 I'll be happy to do it for you!
Go ahead and mod me up. I dare you!
Whenever the Slashdot Question and Answers, or Slashdot FAQ book comes out everyone who contributed online should get a share of the profit. Even the site advertisers should be paying us for our attention.
Slashdot contributers, be aware.
I've been involved over the years in implementing both processes and infrastructure to support engineering teams
Following are some items that may be of help to you
* I like to think of a software development environment as a 4 lane highway in the desert,
where its easy to change lanes and easy to get
off the highway if need be, and easy to get back
on the highway. The opposite of this is a tight-rope, that is hard to get on, hard to stay,
inflexible.
In my experiences, most development environments I've worked in are a tight-rope, as they don't
really provide an environment that help the developers productivity and quality.
* I like to start out by identifying what process, practice, tool will make the project
leads day-to-day work better. Working with the
project lead to enlist team members to accept
the change and then implement on their behalf
* Start out be creating a well known repository
to store all artifacts related to the change:
documents, email, presentations, etc... it can
even be a directory structure at first
* Once some credibility and confidence is obtained
look for bigger wins in terms of improvement.
* Try to avoid creating the tight-rope. For example, some folks may want to write a spec in
text format, others in a word processor, or html.
Let it be a 4 lane highway. So you focus more on
getting buyin for spec writing, then what tool
or format it is in. Later on will be opportuntiy
to refine.
* You can strive for breadth, depth or both in terms of what process, practice, tool you want
to change or implement. Let the owners of the project help you (project leads) determine how
far or how deep to go.
* Create a process change roadmap based on the product roadmap and so you can be sure as to not impact the development teams during critical stages of the release cycle. So is your product roadmap over the next 12 months is to release multiple version of the product, along with patch releases, the process roadmap should span all of
the efforts.
Best of Luck!
Kramer
www.qbal.com
...is such a convenient way to avoid facing your problems!
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
Now I've seen it all!
Appended to the end of comments I post? 120 chars?!
I work on a team of about 20 people of diffrent diciplines. And we are ususally in smaller sub groups so documentation is quite important. What we do is use our CVS (Versioning System) as a sort of mutating users guide.
We have some specific module definitions so everyone will know where to file what. Ie. General docs go in the General Docs, Netwoking Documents for Product X go in the PRoduct X -> docs modules. This also allows the documentation avaliable to be the most current as well as allowing you to view older versions.
Pushin' 'n dealin', shovin' 'n stealin'
We actually use a modified Team Room template on Lotus Notes to archive our documentation, deliverables, discussions, requirements, etc. Full text searchable (including all the attachments), built in review workflow, and more, all accessible via Notes clients or over the web through our Intranet.
we have no idea where to start.
"The "
I am anarch of all I survey.
At the code level, in CF at least, I agree with an earlier poster about Fusebox and more specifically their documentation standard Fusedoc. In short, you state what the file does and define what goes in and out in terms of variable names, types, and scope. At a higher level of abstraction, I find Entity Relationship Diagrams (ERDs) are very useful because they force a group to use a similar vocabulary. Case in point, right now I am developing an accounting module for a larger project. Initial discussions gave the impression "Receipts" were the same thing as "Payments". Au contraire mon frere! They are simliar, but have key differences, that once we used an ERD became apparent. Lastly I agree with using some sort of version control system for your documentation and definitely implement one if your source code is not there already. Makes a huge difference - as long as you remember to back up the archive too!
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 ?
Have you ever programmed PHP? Have you ever read ANYTHING even tangentially related to PHP?
First off, the web-based documentation for PHP on php.net is far better than anything ColdFusion offers. php.net's web documentation outstrips any language I've seen, including ColdFusion. This point, more than the rest of my post, I'd like to stress. php.net is a godsend, I just wish it existed for C and Perl.
I've never experienced the "chasing down of foreigner's components" problem that you've apparently run into. I just appreciate the fact that PHP can leverage all of its built-in functionality, which is quite extensive (SWF, PDF, any database, zlib, the list is practically endless and still growing), with a few decent user-written classes (basically, what you'd find on Macromedia's Developer Exchange).
Next, PHP's syntax is natural for even the novice programmer. Scope, arrays, even variable variables are all handled in a way that makes sense. Based on syntax that an experienced programmer will recognize quickly.
Finally, I've used PHP for a while now, and, of course, have had a lot of questions. All of my questions were addressed either in php.net's docs, the user-added notes, phpbuilder, or somewhere on the Web. So, unfortunately, I never needed to call tech support for $5 a minute.
PHP is open source done right. Please don't knock it with so little knowledge and so much ignorance.
Anything you can do, I can do meta.
Whatever you do, beware excessive standarization. It is natural to require some standard things in every document - for example, that paths in the system where the can files be found should always appear in page 1 or 2. However, I've seen insane systems where even fonts and font sizes are controlled. Tell me. When you go to the Internet, is everything the same font? No. But usually, if you go to a site with "news" that's about the default view you get (i.e., the main page is not the link page instead). In the same way documents should have natural requisites but please do not become rigid past the point of usefulness.
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/
1) Create incredibly complex database systems and the applications associated with it.
:-)
2) Hire a bunch of bright interns at 10 bucks an hour to figure out how the system works.
3) Make the interns write extensive documentation.
4) Write whatever the hell the interns want on their evaluation reports.
5) A win-win situation for all.
I tend to write comments about why a particular API was designed that way and what limitations (be it time or requirements) result from that choice. The main reason I do this is when I have to go back to extend it, I have a note to myself about how to extend or fix it. Murphy's law says the feature you think won't be needed will be the first one requested.
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;
Specific to ColdFusion: look at Fusedocs, DevNotes at HalHelms.com, look at SourceForge for Lee Borkman's WireFrameTool, and look at Fusebox.org for an overall methodology for keeping your CF apps clean. An additional advantage of Fusebox is that it's been ported over to PHP and JSP (with others to come), allowing you to develop all apps the same way, in spite of language. Also, look into Hal Helms's writings about Fusebox as an overall project management technique (Fusebox LIfecycle Process - FLIP)
The best thing about a boolean is even if you are wrong, you are only off by a bit.
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
If you're asking HOW to start off writing a large documentation project, then the method that always worked for me is simply to summarise the screens/forms, then to summarise the items/buttons/commands on each form, and (if necessary) to break down each item into each option. Once you've got this framework, it's quite easy to start filling in the blanks.
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
Browse around http://TWiki.org/ and have a look at the TWiki docs maintained in TWiki (TWiki web) and the developers corner (Codev web) where new features and bugs are tracked.
Do not waste your time on documenting. Formal documnetation is a part of the current trend, where companies tries to escape the fact that they are enevitably tied to the heads of their IT employees.Companies try again and again to view their employees a 'resources', but this view will ultimately fail.
....
...
When the lead programmer leaves your shop it WILL hurt you A LOT. Usually he/she has stored WAST ammounts of knowledge in their heads, and 99% percent of that 'online' knowledge can not be put on paper.
When your system breaks down you do not have the time to wait for the new guy to read documentation for a couple of weeks,to solve your problem. You need knowledge 'online' in wetware NOW. Your only option is to keep your current wetware.
Besides you need to weigh the risk that your lead developer leaves, against the time spent on documentation, its actual value if the guy leave AND the probability that the guy leaves
This rarely goes in favor of doing documentation, but tends to favor making him teach others while he's still around
In a consulting job two years ago I helped a client install an over-priced and under-supported suite of tools called Process Continuum. The "suite" was actually a set of discrete tools that didn't really work together, and I cannot recommend it. However, it contain a gem called the Process Library, originally developed by LBMS, which contained rich project plan templates and outline documents that mesh very nicely with the project plans. Exposure to these materials has changed my professional life.
This type of high-end packaged methodology is designed to help huge organizations run $1M+ projects, and they do not scale down very well. I don't think this is a solution for our cold fusion programmer friend. However, the best practices of building not only standard project plans, but project documentation templates, is an important first step. If one of your clients' methodologies includes one of these huge libraries, don't snub it - learn all you can.
Document everything using your internal best practice documentation templates. As a last step, conform the deliverable to the client's methodology. If yours is good, the conversion will be relatively fast and painless. If you come across an outside idea that's better than what you're currently doing, plow it back into your best practice templates.
The poster has a need for a tool to control documentation content. That's fine. There are lots of good suggestions from other Slashdot readers. But even more important in my mind is the robust base structure and succinct fleshing out of the deliverable documentation.
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
We use our source code repository for documents as well as code, keeps everything in the same place. The repository is split by project with the relevant documents for each project in that projects area. People check docs in and out in the way they would source code and you can always track down the latest version of the documentation
a p.htm
As for the format and content of the docs you really have to think about what they are for, specifiactions for users to comment on and specifications for programmers to code from need to be different. Documentation also becomes useless if you can't keep it up do date so keep it at an appropriate level of detail.
One example is to think about a new programmer coming onto the team will the documentation help them get up to speed quickly?
As for document formats there are lots of examples of standard docs on the web. Check out Steve McConnels company Construx
Both the project survival guide site http://WWW.CONSTRUX.COM/survivalguide/
and there methodology templates http://WWW.CONSTRUX.COM/cxone/CxOneBasicDocumentM
but there are lots of others around
"I deny nothing, but doubt everything." Lord Byron
What next , people using FrontPage get called computer scientists?
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
in which case the comment says what should happen, and the code says what doesn't. It's easier to compare the code against a good comment than the code with "// ..."
Short documentation can be useful. I'd say it can be the most useful documentation. Reading the code can tell you about the low-level design decisions taken, but it does not give you the big picture. A short, high-level, document can be invaluable for placing the low-level information in context. For example, telling someone that the product has a database holding customer data, and extracts order data from system XXX, and has a YYY user interface, etc. This information is useful for only new team members, but they are the ones who need documentation.
Ne mæg werig mod wyrde wiðstondan, ne se hreo hyge helpe gefremman.
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!
Firing people who want to do things "the right way" is one of the worst things you can do. The others will see that there is no room for any thinking about what you're doing and churn out stuff that barely works and nobody can read.
Instead, try thinking why "the right way" doesn't fit. There are lots of heavyweight "right way"s which don't fit a small company. But there IS nothing wrong in looking how you can achieve better quality by doing some things consistently one way round. The two books I know of which present better methods for software development (one about XP, the other about CD) both include a chapter of the kind "Don't do it the way I told you if...".
If they keep pestering you with "the right way", discuss why the way you do it now is better or not. Do some analysis of the risks and costs involved. But don't forget doing real work in the meantime. If they still don't get it and won't see why their "right way" doesn't fit, start thinking about firing people.
- Documents your clients asks you to give
- Things you explain twice or more to different people
- Delays caused by misunderstandings or simply the absence of communication (e.g. useful comments in the code).
You can find out where these breakdowns occur: everyone who does a task (something that takes less than 2 days) gives an estimate of the time he/she would need in an ideal world. Afterwards, you check the "ideal" numbers against the real time used. Compare these ratios and try to find out what has happened. You will find that either the estimate simply was too optimistic (they are at first) or there was something unnessecary which was in the way, possibly something which could be improved whith better communication.
Once you know what has to be communicated, look for the technical solutionVideo tapes may be better than no documentation, but I think it's awkward if you look for something and have to watch all the films if you're looking for some detail.
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.
We use WebCONTACT for project management, contact management and also helps keep track of the hours well. It's fairly cheap (about $10.00CDN/mo. or $7.95USD/mo. per seat on both prices) and does what it's supposed to do. That's a good way to manage products, as for documentation, I would highly suggest documenting all procedures for doing anything in the office, then document stuff like coding standards, who to see for what, and put it all in a central place. No one should ever have to guess where their documentation is, they should hit some internal website and see it all. And as for where to start, the answer is simple. Document everything. :)
I don't know whether you have a source code respository but we manage all our documentation using a combination of our perforce which runs on our linux and windows boxes and having accepted pracices for the use of collaboration tools such as groove and webloggers.
All useful information is stored in a respository and may be accessed from our intranet website. We're investigating using XML to categorise our knowledge base. We do some work on knowledge management so technically the group I work for should be good at this and our current processes seem to work well. Don't underestimate the need to have formal documents emphasising that knowledge is your most important resource and outlining how everyone should achieve it's management.
I strongly suggest that you have a professional and experienced technical writer for this. That's what they're for. You don't want this to be a burden to the tech folks. The technical writer should have experience creating and managing document control systems.
Perforce is a good document control system to use. It lets you check things in and out. You can set up different projects and so forth. It's easy to learn and use.
The Law of Falling Bodies
for javadoc like code documentation one can use doxygen.. it can be found at http://www.sourceforge.org
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'm in the process of creating a documentation system similar to the docs at MySQL... basically it'll be database-stored, and allow user comments, but it'll have security features so that you could set it to only allow members of your company to add comments, if you so chose.
:-p
:-)
The only catch? It's written in a language called RACE, which you haven't heard of yet. Why RACE? Because it's better and easier than anything else I've used. We (mostly my boss) developed the language in-house at the web design firm I work for, and I have trouble going back to coding in Perl and other languages because RACE is just so freaking easy and neat...
The good part - RACE is freeware, runs as an apache module, and is easy to install on any *nix platform. However, you may want to wait until I'm done with redocumenting it and put up the latest source code.
What the hell is RACE? It's a tag based language that can do just about anything PHP, Perl, Coldfusion, and ASP can. www.racekit.net for more (outdated, more on that in a sec) info...
We're up to version 2.9.2 now (I believe the site download will give you 2.5.4 or something), but since we never really "advertised" the site, we haven't updated it in a long time. We've just gotten an identity for RACE created by a design firm, and are in the process of redesigning the site to accomodate my documentation etc... Until now the site has mostly existed just for us to go grab the [old] PDF documentation
All of this should be ready in the next couple of months, I'm hoping.
If you want the latest source, with instructions on how to use it, let me know. And if you want to see a site that uses it, check out http://www.openingbands.com -- it's entirely RACE driven/managed.
Okay, this sounds more like a RACE ad than help to you -- so let me get to the point... I have a feeling RACE is what you're looking for because whether or not you end up liking what document management software I finish up (which I'll release for free) - you could write your own really easily, and really quickly.
Bottom line - if you want a document management system that fits your needs, you're probably going to want to write it yourself, or you'll be jumping around shortcomings of each different piece of software. I suggest you try writing it in RACE because I feel it'll be fast and easy to do (if you want the latest source code just email me). Of course any other language you're comfy with is fine too
Steve
http://www.babysmasher.com
http://www.openingbands.com
Early on in my career, I wrote a great deal of docs & was responsible for getting the coders to document their stuff. Here's what I found works:
1. Internal code docs: make it a requirement that interfaces and subroutine behavior are documented. Enforce this with code review (which is a great idea anyway). File noncritical bugs against undocumented code. Do this enthusiastically, and eventually your coders will expect to see good docs in their fellows' code.
Tools: freeform embedded docs are OK here; they're only read by programmers. If your group has a code style policy, add a doc style to it.
2. Programmer docs: it takes a programmer to write docs for programmers, and the internal code docs mentioned above won't cut it when you need to create an API manual. Instead, you'll either have to be lucky (or medieval) enough to find (or force) a programmer to generate the docs, or you will have to train up a tech writer to be a programmer. The latter is slower, but overall more effective.
Tools: Programmers read docs while writing code, so that means paper output or docs they can view in or near their code editor. Plain HTML is surprisingly poor for reference docs, but if you add effective searching & automatic crossrefs, it's OK (see the online Apache docs for example).
I like creating docs in FrameMaker (from Adobe) since it outputs serviceable HTML w/indices, graphics, & crossrefs, has an excellent WYSIWYG editor, gracefully handles massive documents up to encyclopedia size, prints books well, is available on Win/Mac/UNIXen, and (very important) stores files in a diff-able (plays well with CVS) format.
3. End user docs. These are best written by a tech writer who's also a power user. You'll find that most programmers are not power users; they know their own bit of the system extremely well, but bupkus about the rest and often aren't really interested in using the whole product for which they're coding. Make sure the people selling/promoting the product review end-user docs, too.
4. File bugs against docs. This has been mentioned elsewhere, but it bears repeating: treat errors and missing features in your docs at least as rigorously as you treat code bugs. Make sure the support folks can and do file bugs; they're the people who hear about the bugs after release.
Tools: gnats is the bomb: simple, cheap, modifiable, works anywhere. Make a doc-bug category that your writers manage.
5. Put tech writers on the engineering team. Many organizations think docs are sales materials or something, so they put the writers in the sales, marketing, or support department. This makes for bad docs. Instead, tech writers should work next to and at the pace of coders. Ideally, doc writing starts as soon as the design phase completes. (You do have a design phase, right?) Good in-progress docs are an excellent roadmap for the coders, and result in the docs & code converging on completion at the same time.
6. Hire or grow professional writers. Pretty much anyone who speaks the language can write good docs, but only people who like writing will stick to it through ten releases. Personally, I didn't know I liked writing until someone hired me to do it. Presto, professional writer!
First off, hire a technical writer. And do so as fast as you can.
Of course, there are some problems with this statement, the first being that the technical writing industry itself hasn't the first clue what it should really be doing.
Maybe I should say, instead, hire a good technical writer. What makes a good technical writer, you say?
A good technical writer:
That's the short list. Far, far too many technical writers fall into the trap promulgated by the TW industry as a whole, which appears to be:
I consistently encounter "technical writers" who seem to think that what worked in their Master's dissertation at UC-Berkeley is what will work in this industry. You can easily identify bad technical writers by the fact that they're slow (1 week or more to produce a document), mistake bureaucracy for procedure (a good procedure is minimally invasive, and works around the expensive folks like programmers rather than the writer), and, for some reason, can never quite get things done on time because it's too complicated.
It's also entirely unnecessary for your technical writer to have a degree or certificate of any kind, regardless of the (again) technical writing industry's opinions. What matters is what they can produce. The questions you should be asking of any prospective technical writer are (among the usual for any new employee):
You get the idea.
When you interview a technical writer, submit them to a simple test, which should be most of the interview in a nutshell.
Make them write something for you. Put them with your most turbopowered supergeek for an hour, have your supergeek describe one of your company's product components to them, and have the writer document what they hear.
Any competent writer should give you something concise, clear, and reasonably elegant within a day or two, no longer. If they can't, you should seriously question whether they're worth hiring.
My $.02 as a technical writer who is, apparently, unqualified in the eyes of the TW industry to hold either my current job or my last five jobs,
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
I've been doing technical writing with a few different companies (despite my engineering background), and I've found that the most workable solution is to just use Microsoft Word and email, with the final versions put up in shared folders on a common file server. As long as the set of documents in use at any one point in time is relatively small (even if the total body is large), this works just fine, even with distributed workgroups and erratic (offline) network connectivity.
If you have a huge volume of documents that are in constant collaborative use, or people frequently take documents off site for long periods, consider using CVS or VSS for check-in, check-out ability. In practice, I've almost never used version control, however.
As for distribution of drafts and collaboration, everyone I've worked with always uses email. Despite the prevalance of all sorts of neat tools, email just has the tightest and most convenient integration with everyone's workflows. It definitely has its problems, but its problems are less than using anything else.
The most difficult part of the documentation process is not technical, it's personal. Once everyone is in the habit of documenting things in digital form, the details solve themselves: If you don't have a central server, people will just send it back and forth in email, and that works fine. If you don't have version control, people just write change histories into the documents themselves, and that works fine. If you don't have the same tools, everything goes to the lowest common denominator (GIF and Word, or even HTML, usually), and that works fine.
In reality, if at all possible, just using *only* email works great. As long as you can get by without fancy formatting (or are ok using HTML-enhanced email), it works great. Everyone will end up mailing all the documents back and forth, and your email server will inevitably turn into your primary file server anyway (the latest server is always in your inbox, not on the file server), so just realizing this up front keeps everything simple.
Indeed, I'd recommend starting out with a minimum of rules strictly enforced, rather than a few that are lenient. Were I to pick a single rule that solves most issues, it'd be "Return document reviews or a new ETA within 24 hours, always. No exceptions." In this way, progress always continues despite any technical problems.
When it comes to documetnation processes, less is more. People are smart -- let them figure out the details as they come up.
(With the risk being offtopic - sorry!)
When maintaining and expanding software, the documentation you usually miss in a project are decisions that have been taken along the way.
You know, the things that makes you go "That's an awkward solution. Why in the world did they do that?!"
(E.g., it may be because of implicit customer requirements, or bugs in third party software, that otherwise would have been the obvious choice.)
Since these decisions are above source code, yet below the 'requirements and specification'-level, they often go undocumented, and then the guys who inherit the project have to start all over.
No sig to see here. Move along.
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.
The Fusebox community (ColdFusion, Java, and PHP) has created an XML-based documentation system that's quite popular. There's info on it at www.fusebox.org.
Before that, my username was Anonymous Coward.
I use weblogs much like slashdot because you can secure it via your web server and people can create accounts and the input can be moderated.
Not to mention that searching is nice and easy, and for new employees they can pick up on it very quickly.
- Sonnyjz