Software Documentation Standards?

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?"

Comments

PHPDoc

[Johann]

For technical specifications of your PHP scripts, classes, etc., I recommend PHPDoc:

PHPDoc is an adoption of Javadoc to the PHP world. PHPDoc is written in PHP. It offers you a way to generate an API documentation of objectoriented and procedural code with certain markup in your source. PHPDoc is an Open Source Project and gets distributed under the PHP Licence. That means you can use it in commercials projects.

--
"In the land of the brave and the free, we defend our freedom with the GNU GPL."

Doxygen

[ryants]

Well, I don't know anything about PHP scripts, and maybe this response doesn't apply to you... if not, sorry.

In the C/C++ world Doxygen 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