Re: Software Documentation
In my office, some of us are having a debate about the appropriate content for a
document set for software, such as requirements, use cases, design, and so on.
Is there a good source that outlines what a good documentation set is and
what each document should include? Part of the confusion is over who the
audience is as well as how to include information that changes frequently.
Most of my clients have used some version of the IEEE standards for software life-cycle documentation to define their document sets. The older IEEE standards are still available in many company and university libraries.
The current version is a draft of what will be the next ISO standard:
P15289 - IEEE Draft Standard for Systems and Software Engineering - Content of Life Cycle Information Products (Documentation)
This description is on the IEEE web site:
"This International Standard specifies the purpose and content of all identified Systems and Software Life Cycle information items. The information item contents are defined according to generic document types and the specific purpose of the document. The generic document types (which may be referred to as information item types) are to be used to identify the information necessary to support the ISO/IEC 15288:2008 agreement, enterprise, project, and technical processes; the ISO/IEC 12207:2008, primary, supporting, and organizational life cycle processes, or the ISO/IEC 20000-1:2005 Service Management processes."
All the document types you mention are included, as well as at least a dozen more, with specific recommendations for content and structure of each type.
IEEE and ISO standards are not available online, as far as I can find, except by subscription (requires IEEE membership). They are available for purchase, but are extremely expensive. Unless your company already has a copy, or are willing to buy it, your best bet might be the nearest college that has an technology or engineering library.
--
K@
Kat Nagel, Owner, MasterWork Consulting
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days.
http://www.doctohelp.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com
To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com
Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.
Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat
References:
Software Documentation: From: Sue McKinney
Previous by Author:
RE: FrameMaker X can ONLY be activated over the internet
Next by Author:
BIZ: "Facebook Service. A new Password is sent you! ID168" (cross-posted)
Previous by Thread:
Re: Software Documentation
Next by Thread:
WritersUA - cab share from LAX, Sunday 5:30-ish
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads