Software Documentation Standards? 11
CynicTheHedgehog asks: "I am a programmer for what used to be a small CLEC in the Southeast. Initially I was in charge of system administration and development of small PHP scripts under little supervision and absolutely no quality control. I now work with an entire team of developers under new management, and recently there has been a major push toward mature development practices, not least of which is project documentation. The problem I am experiencing is that up to this point each of us was in charge of his respective projects, more or less managing them from conception to completion. That being the case, the documentation solutions we have come up with have been something of a mix between technical specifications and your typical corporate red tape. Our processes are poorly defined at the moment and I'm trying to come up with a solid, standards-based documentation solution. An SRS is a bit heavy for what we're trying to do and doesn't provide the 'sign-off' points we need to cover our rears. What kind of documentation formats are in place at other companies? Are there any defacto standards in the open source community that are useful in a corporate context?"
Learn by example? (Score:1)
Appologies for the double post (Score:1)
Red tape? (Score:1)
Quite Possibly Not All That Much... (Score:2)
"Have you produced your ISO nine-thousand thingy documents yet?"
"Nine thousand thingy?"
"Yeah, nine thousand and two, oh no, nine thousand and one, that's it, we've not moved on to nine thousand and two yet. You do know we're getting audited next week?"
"OK, how do I do them? Is there a training course I can take, a guide somewhere on the intranet?"
"No, do what we did. Copy the DBA team's one off the intranet and change whatever words you need to make it fit your team. They've been passed already so we know their's is right."
"While we're on it, what about normal code documentation?"
"Oh, don't worry about that. The ISO stuff's all the senior management understand anyway as it makes us look good to the customers. They don't want you wasting time on something like standards, they'd rather you looked busy coding."
Depressingly, that's exactly how life was inside a company that pretty much openly admitted that if they could ever get their billing system to operate properly and bill for all of the calls, they'd double profitability.
The moral of all of this is, the more I move around from company to company, the more I find that everyone seems to live in hope of there being some coding standard somewhere because they sure as hell don't have it. There are occasional pushes to move to one and a company specific one tends to get drafted and then generally ignored ever after.
If anyone does have information on a good standard and can give it without ever mentioning Z, I know I'd love to hear about it too. Until then, don't beat yourself up - University taught us there were these mythical grails but they seem to be almost non-existant in a real world that would much prefer quick results now to documented ones later.
Code Standards (Score:2)
In the code standard specify everything, from indentation style to what types of comments should be in the code. For more advanced documentation systems, have the standard describe *exactly* what is expected-- file headers, function declarations, the works! Provide templates and examples. Even write a tutorial if you're working with people that *still* don't get what's expected of them. Just make the standard as unambiguous and detailed as possible.
And of course, make sure it's used. Unfortunately being excessively fascist about it will make you unpopular (so don't do that!), but make the standard come across as important and make sure it does get followed.
Re:Red tape? (Score:2)
Main Entry: red tape
Function: noun
Etymology: from the red tape formerly used to bind legal documents in England
Date: 1736
: official routine or procedure marked by excessive complexity which results in delay or inaction
--
Advice (+ annoyed rant) (Score:2)
For example, you may find that developers and others aren't aware of other projects in the company, their purposes, and their progress. To fill this need, you might decide you need a project plan written for each new project. These can be simple (a couple of pages describing what you're making, why you're doing it, what you need from other people to complete the project, and when you're gonna be finished) or elaborate (up to a full, detailed specification). What's important here is to decide what information needs to be written down and accessible for each project, and produce some kind of specification or template document for that information. I find templates usually get the best results: it's relatively simple for a programmer to clone a document and fill in the blanks, doesn't take too much time.
Or another example: you might find that programmers want to re-use code but are having problems because of variance in coding standards, no or lame comments, and/or lack of interface documentation. This would indicate you ought to
- promulgate a standard for naming, indentation, or whatever is causing readability problems (good idea to avoid specifying any more than is necessary to achieve mutual intelligibility among the programmers)
- require people to comment their code, and provide templates (again)
- start formally documenting interfaces instead of assuming people will spend the time to pull the info out of the code
Now for the rant. WHY are technical writers given so little respect in the open source and Linux community? I hear endless complaints about the quality of documentation - and not just from users - but almost never do I hear "Hmmm, you know, there are these people who know how to do this stuff, and even specialize in it. Maybe we should get one to work on the docs!" Instead I hear about how programmers should hire an intern for a couple of weeks to throw together some documentation - after all, docs are easy, any apprentice programmer can do it just as well as a writer with ten years of experience, right? - or about how documentation is just an afterthought and you can't expect it to be good. Argh.
If you need docs or documentation standards, why not hire a tech writer? This is what tech writers do for a living!
Information Maping (IMAP) (Score:2)
IMAP (no, not the mailbox standard) is a very sensible standard supported by major corporations, in fields as varied as aeronotics and chemistry. We have all seen this documentation system before, in Nokia or SUN manuals, for instance. Unless you can afford to actually hire professional technical writers - with a fat salary to match their expert knowledge of your field, on top of grammar and documentation technique - to create you a customized documentation system and adapt it to every project, sending a few people to IMAP training is your best shot. Several IT consulting companies around the glode provide training, such as this one [slashdot.org]. You might also wanna read this technical writing primer [fishpool.fi] to give you an idea of other issues to consider. Good luck!
Been there, done that (Score:3)
If it helps, several of the IEE documents refer to corrisponding ISO documents, so you might try there.
PHPDoc (Score:4)
For technical specifications of your PHP scripts, classes, etc., I recommend PHPDoc [phpdoc.de]:
--
"In the land of the brave and the free, we defend our freedom with the GNU GPL."
Doxygen (Score:4)
In the C/C++ world Doxygen [doxygen.org] is getting a lot of attention as a standard documentation tool.
Anyways, like another poster has said, look around: that's the great thing about Free Software. Check out what KDE does (I think they use DocBook, but don't quote me). Check out how the GNOME guys keep themselves on the same page (no pun intended). It's all transparent and readily available for you to check out.
Ryan T. Sammartino