About documentation standards

Documentation is such a thing that few people have warm feelings for: boring, boring, monotonous. And, nevertheless, sometimes there is no doubt about its necessity: after all, someone after you to use it or, moreover, modify it. And then the question arises: how to make the documentation right?

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

In order to form your opinion without shoveling the articles, you can go in two ways: trust in some authority or look at the standards - that's where the problem is most likely thought from all sides.

Someone might say, “ah, 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 - finding the right thing is not difficult. And besides, well, it’s necessary to soak up the standards section already, otherwise it hangs empty, even offensively.

Our.

We turn first to GOST- s. They are frustrated by the development dates (however, it seems that not much has changed in the documentation over the years) and are pleased with the free.

GOST R ISO 9127-94 “User documentation and information on packaging for consumer software packages” is the most liked standard among ours. Quite briefly (the entire document is about 20 pages), the basic requirements for the composition and content of user documentation are indicated.
Official page. Download PDF.

GOST R ISO / IEC 15910-2002 “The process of creating user documentation for software tools”- the standard no longer answers the question “What” should be in the document, but “How” the document should be created. Additionally, there is a detailed description of the style of the document with an example - it’s quite a convenient thing for creating a template: you steam it up once (and hammer everything into the template: from alignment to the format of the captions of the pictures), and then you glue documents of all the same type, and not with different font headers.
Official page. Download PDF.

GOST-s 19.hh series - a series of ESPD , passion, what old (on average, the documents created in the 78 th year), but the same laconic as in ISO 9127, requirements for many types of documents.
Familiarize.

GOST 34.602-89 “Terms of Reference for the Creation of an Automated System” - standard for technical specifications. thanksJazzist .

Bourgeois.

There was no limit to my indignation when I found out that international standards are not free. It’s like making traffic rules 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 the usual way, in a pirate 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 architecture of the software , that is, for the technical description.
Official page.
I especially liked the tablet-extract of the main content of the document (here a free translation):

Type of review	Content	Attributes	Presentation Examples
Decomposition	Partitioning the system into structural components	Definition, type, purpose, functions, dependent entities	Hierarchical decomposition diagram, verbal description.
Dependency Description	Description of the relationships 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 details	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 and preparation of user documentation for application software" - recommendations for creating user documentation. So to say, advice to the "mistress of the note." A pretty nice guide with a lot of examples (IMHO, more suitable for reading before or at the very beginning of the creation of documentation, since 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”- quite fresh and, judging by the content, a useful document. But, apparently, due to its freshness, this standard is nowhere to be found for free. At least I could not do this.
Official page.

These were the standards most closely associated with documentation. They can be useful both for a beginner techie, and, for example, for a freelancer, who “is both a Swiss and a reaper, and a dude is a dude”.

Clarifications, additions and useful links are welcome)

UPD : a very informative comment , thanks lkochetova

UPD1 : my conscience tortured me, and there will no longer be direct links to downloading standards that are not freely distributed. If you need them, it’s not difficult to google.

UPD2 : also see the article Documentation in accordance with GOST 34 * - this is just a detailed analysis of domestic standards for project documentation.