Documentation Standards

[Jim Bassett]

Our shop has a documentation problem where as we have no standard to go by. Everyone creates a requirements and design documents in different sytles, and it is always a problem getting documents approved because those doing the approval all have different opionions about what these documents should contain, etc. Other than for IEEE are there standards, tools that could help us?

Thanks

Jim Bassett

[Tomaz Stih]

Use UML. It has standard notation for everything except requirements. I don't think there is any formal method for requirements available. But after all requirements are just strategic guidelines for software product such as:
- the product should enable quick response to customer request for mechendise (max. 15 sec.)
- the product should enable easy data entry
Everything else is analysis and design. This will cover your software(technical) documentation.

It will not cover entire company documentation. For example there is no project documentation in UML. For such documents I suggest you read the standard requirements and create the document templates yourself consistent with standard requirements. Surely there should be a book around on ISO 9000.3 with examples of proposed structure of possible documents that make process ISO compliant.

Also try to encouradge using standardized tools (for example MS Project for project management, MS Word for documents, HTML documentation for code).

To enforce consistency for all company documents use document management solutions. Good ones force you to obey some rules (for example document versioning, document structure, personal responsibility)...

---------------------------------------------
Tomaz Stih, B.Sc.CS tomaz@nameco.com
Ob sotoccju 10 Nameco Group
SI-1000 Ljubljana http://www.nameco.com
Europe