Slashdot Mirror
Beginning Project Documentation?
mirthe_v writes "Hi, I'm working for a small webcompany (about 20 people), with ColdFusion programmers and designing staff. We all work on a bunch of projects (Internet, intranet, cd-roms, etc.) on the same time, with different people and different or no methodologies. There is an ever growing need for documentation, but we have no idea where to start."
mirthe_v continues: "I was just wondering how other people/companies keep track of their current and older projects.
Do you put stuff in a database, if so, what about all those diagrams and handwritten notes.
If not, do you store things in a folder per project, and how do you then stop documentation from getting lost and making sure people store things where they should.
"As I said, I don't know where to start, especially since the staff varies greatly in the need for documentation, technical background, experience with writing documentation and even different languages (English and Dutch).
"Please share all your thoughts and experiences. Cheers, Mirthe""
I always liked the record keeping as done in the biotech area... Every scientist has a lab notebook (offline) where references are made to everything that was done (and where things can be found).
:)
I'm always suspect of documentation and record keeping that is 100% digital. If the notebooks are witnessed and microfilmed, there will never be a question on when the work was done.
If notes about how things are done are kept on a notebook like that, it is a lot easier to go back and figure out what was done and how it was implemented when it comes time to writing real documentation. This does not address the inprogress documentation, but you should not forget about the tracking aspects. (CVS is good, but it could be falsified easier than a notebook I would think).
Don't get me wrong, I hate doing this... but it is a good idea
DrArt
-- Huh?
I don't know about hiring someone new but couldn't you just start by compiling comments and formatting them into a reasonable sounding document? Are you looking for user manual type documentation or comment style docs for coders or what? The longer you wait to get this rolling though, the worse it will get, that's for sure.
"Growing old is inevitable; growing up is optional."
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?
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.
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.
Or, if you want to use PHP, try PHPwiki, at http://phpwiki.sourceforge.net/
I'd give a working example of a wiki, but I'm worried about the Slashdot effect on it -- the guy might run up bandwidth costs (and he's not my enemy), and it might become too popular (which means too expensive to run, and it means that it would be edited too quickly and by too many people so that it would lose its small-community feel that Slashdot has also lost).
Start with documenting the code first! Since the code is what must be
maintained in the long run, this is the critical place to make sure you have
decent documentation so any programmer can pick up where the last one left off.
Well documented code should contain as much comments (if not more) as
code.
Once the code is well commented, pull the comments out and use that as a
start for technical documentation, a reference to the design, functionality, and
interaction with other programs, modules, etc.
Once this is complete, then, and only then, should you start documenting the
programming project as a whole, mapping out database layouts, etc. (note: this
is from the standpoint that you did not do it correctly the first time and are
basically working from scratch). No matter what you use to document the system
in, it should be a common format between all projects and systems. Databases
should be documented using a decent data modeler, and don't forget to document
the stored procedures (in the procedures as well as external
documentation).
Once all the technical documentation is complete, then you should start
thinking about documenting the project from a user's point of view. If a system
works well and is easy to navigate, the users will rarely reference a help file.
I have walked into too many projects that were completed in haste, and looked
at way too much code that was not commented at all to know that had the previous
programmer done his/her job well, it would have saved me half the time trying to
understand why they had done something the way they did. When writing code it's
easy to assume that the code you write is blatantly obvious, but to someone not
knowing the system from the start, it won't be, keep that in mind and all your
code will end up being well commented, and writing documentation will be easier
later for anyone looking at the system.
In the future, remember that a well organized programming project will
involve much more planning and pre-documentation then actual coding.
http://www.codewolf.com - Just good stuff to waste time
You're just jealous that someone using ColdFusion can do something in half the time it would take using PHP.
Seriously, because it's "closed source" it's bad?
A good analogy would be Apple. Yes, Macs cost money, and OS X is not open source. But a Mac with OS X is far more elegant and easier to work with than a Windows PC.
Similarly, ColdFusion costs money and is closed source, but is easy for new people to understand, and incredibly powerful at the same time. It has a plain-english syntax that actually makes sense, and has tons of built in functionality that let you get work done, instead of chasing down some PHP component that you read on a message board might work if you can track down the guy who wrote it in some foreign country. It's backed by Macromedia, a real, permanent, profitable company that has tech support and a phone number.
Perhaps you're just scared that someone without a CS degree could take your job using ColdFusion?
Its very useful learning excercise for the new person to start documenting the current project. As they will actually learn what everything does as well as having to talk to everyone else when they encounter something they dont quite grok and need an explanation.
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?
Maybe you mean something different here, but Literate Programming is a field, invented by Donald Knuth, that has little to do with what you are saying here.
There are many good reference, try this one, for example.
AFAICT, the tradition of Literate Programming comes out of Mathematics where proofs are given as narrative, but the equations (programs by analogy) are terse.
For example, this example, written by Knuth himself, contains many example of terse variable names like rx, h, t, l, etc.
TWiki, a flexible, powerful, and easy to use Web-based collaboration platform has worked well for us.
http://www.twiki.org/
You can actually use the javadoc tool that comes with the JDK to spit out html documentation on any language, it basically just looks at your functions. I've seen it done on C code and works nicely
[alk]
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.
This is true and it can cost them dearly. My wife's company recently did a review of their products and that included feedback from customers. It turns out that in the past six months three big customers are considering moving to a competitors products because of lack of documentation. The company previously had decided to outsource all documentation to India as they figured there had to be something written up but they did not see the benefit of quality documentation. Additionally, a good technical writer may have experience in other arenas such as interface design. No offense to the full time programmers here, but some of you folks create the most attrocious interfaces I have ever seen and could use a little direction when it comes to interface. It may make sense from a technical standpoint, but put a lousy interface in front of an end user and they can be totally lost.
The other issue is when companies try and cheap out on documentation and hire "writers" that have no experience or training in the documentation arena. What results is poorly managed and poorly documented projects that can cause more harm than good. My reccomendation is to find someone that has several years experience and preferably a masters degree in technical communication or better. Like most things, you generally get what you pay for, so don't cheap out.
Visit Jonesblog and say hello.
The first thing you should do is create coding standards in which documentation is part of the coding process. The documentation standards should be such that you can automatically generate documentation as the code base changes.
For example, on every Perl project I work on these days, I introduce a script (about 30 lines of code) which auto-generates documentation from the PODs. The script can be run as a cron job that auto-updates the online documentation every week. That way, coders document as they go, and central documentation resource automatically regenerates itself on a regular basis.
The second thing you should do is set up an intranet site (behind the firewall!) for developer documentation. Include the auto-generated documentation, documents describing your coding standards, project management documentation for developers, use cases, class diagrams (does ColdFusion even have objects?), activity diagrams, sequence diagrams, etc., etc. If you have a team of 20 people, undoubtedly you have someone who manages code revisioning. Likewise, managing the developer intranet should be included in someone's job description, and, what's more, they should be given the time to do it properly.
Hope this helps
-- My choice of computing platform is a symbol of my individuality and belief in personal freedom.
Read The Mythical Man-Month by Frederick P. Brooks, Jr. (ISBN 0-201-83595-9). This is one of the best books I've ever read when it comes to managing any sort of software product - and it gives great advice, including a chapter on documentation and why it is so IMPORTANT.
Please, go out and buy it and read it - or check it out from your local library. It is a must for all programmers, even if you're not the one in charge.
Jake
Dating: while( 1 ){ call_girl(); get_rejected(); drink_40(); } return 0;
For some reason I highly doubt that Fusedocs are a substitute for proper system analysis and design. Sure, it might be smart enough to analyze the interrelations between modules and create class diagrams and generate documentation. However, automated systems still have a fundamental flaw: while they can tell you how everything is interrelated, they can't tell the people using the documentation WHY it was implemented the way it was, which has CRITICAL implications for maintenance. Automated systems can reveal structure but not purpose.
Also, tools that generate documentation from code give you the design documentation just when design documentation is the least helpful. At best, documentation of this kind will only serve to show you how brain-dead your initial design was (because by the time the tool is useful to "reverse-engineer" your code it's already far, far too late to correct your boneheaded design gaffs).
Finally, the title made sense to me but yes, it is a double negative; consider it revised to "Documentation can't be pulled from the ether...". Creating the documentation from nothingness is a classic case of selling the horse to buy the cart.
-inq
I'm new at my current job (3 months now), and am in the lucky situation that the guy who wrote all code I have to work with is sitting right next to me to explain it. But then still... it's a madhouse around here so he doesn't always have the time for it.
The least you can do, is document the reasoning behind what you coded (needs to be no more than 5% of the code you wrote), and let the code itself tell the rest of the story. Without that small fraction of documentation you will get lost, unless you've had the exact same training as the others who work on the project.
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.