About documentation standards

Documentation is such a thing, to which very few people feed warm feelings: boring, boring, monotonous. And, nevertheless, sometimes there is no doubt about its necessity: after all, someone after you can use it or, even more so, modify it. And then the question arises: how to make the documentation right?

There is a lot of articles on the topic “how to write documentation”, but if you decide to take it for the first time, it’s not immediately clear in a new area for you whether the author writes it or invents a gag.

In order to form an opinion without perepepachivaniya articles, you can go two ways: trust no one authority or look at the standards - already there is the most likely problem thought about from all sides.
')
Someone might say “ahh, standards! they are even more hellishly boring than the documentation itself! ” Well, let's not lie, there is a little :) But if you have a document in electronic format - it is easy to find the necessary. And besides, well, it is necessary to soak the standards section already, otherwise it hangs empty, even insulting.

Our.

We turn first to the GOST . They are frustrating with the development dates (however, it seems that not much has changed in the documentation during these years) and they are gratifying for free.

GOST R ISO 9127-94 "User Documentation and Packaging Information for Consumer Software Packages" is the standard I liked most of all. Quite briefly (the entire document is about 20 pages) the main requirements for the composition and content of user documentation are indicated.
Official page. Download PDF.

GOST R ISO / IEC 15910-2002 “Process of creating software documentation for users” - the standard does not answer the question “What” should be in the document, but “How” the document should be created. In addition, there is a detailed description of the style of the document with an example - quite a handy thing to create a template: once you mess up (and stuff everything into the template: from alignment to the image caption format), and then you rivet all documents of the same type, but not with different font headers.
Official page. Download PDF.

GOST-s of the series 19.xx is a series of ESPD , a passion that is ancient (on average, documents were created in the 78th year), but the same laconic requirements as in GOST 9127 are requirements for many types of documents.
Familiarize.

GOST 34.602-89 "Specification for the creation of an automated system" - the standard for TK. Thank you jazzist .

Gourmet.

There was no limit to my outrage when I learned that international standards are not free. This is how the rules of the road make paid. But in principle, it may be reasonable: organizations are not state-owned. They want - they can take money for their work. Fortunately, many standards can be downloaded in a familiar, pirated way.

IEEE Std 1063-2001 "IEEE Standard for Software User Documentation" - the document outlines the requirements for the structure, content and format of user instructions.
Official page.

IEEE Std 1016-1998 "IEEE Recommended Practice for Software Design Descriptions" - recommendations for documents describing the software architecture , I mean the technical description.
Official page.
Especially liked the extract of the main content of the document (here a free translation):

Type of Review	Content	Attributes	Presentation examples
Decomposition	Breaking down the system into structural components	Definition, type, purpose, functions, dependent entities	Hierarchical decomposition diagram, verbal description.
Description of dependencies	Description of the relationship between entities and system resources.	Definition, type, purpose, dependencies, resources.	Structural diagrams, data flow diagrams, transaction diagrams.
Interface Description	A list of everything that a designer, programmer or tester may need to know in order to use the structural components of the system.	Definition, functions, interfaces.	Interface files, parameter tables.
Description of parts	Description of the internal structure of parts of the entity.	Definition, data processing, data.	Flowcharts NS diagrams, PDL

ISO / IEC FDIS 18019: 2004 Guidelines for the design of user documentation . So to say, advice "hostess note." Quite a nice guide with a large number of examples (IMHO, more suitable for reading before or at the very beginning of the creation of documentation, as it approaches the process thoroughly, from the planning itself). Also in the applications there are checklists “what not to forget to do in the process of developing documentation” and “what should be in the document”
Official page.

ISO / IEC 26514: 2008 “Requirements for designers and developers of user documentation” is a rather fresh and, judging by the content, useful document. But, just, apparently, because of its freshness, this standard is nowhere to be found for free. At least I failed to do this.
Official page.

These were the standards most closely associated with documentation. They can be useful to both a novice technician, and, for example, a freelancer, who “is a Swedish player, a reaper, and a dreamer”.

Updates, additions and useful links are welcome)

UPD : very informative comment , thanks lkochetova

UPD1 : conscience tortured me, and the article will no longer contain direct links to download standards that are not distributed freely. If you need them - google is not difficult.

UPD2 : also see the article Documentation according to GOST 34 * - it’s just with a detailed analysis of national standards for project documentation.