How to cope with the versioning of software documentation and the software itself?

I need experience with software documentation and user guides.

When I write official documents, such as software specifications, each document receives a version number, and the document has a history of changes after the table of contents, where you can track the changes made to the document.

If I am writing software documentation or a user manual for the application now, and the software has version control itself, you can confuse the version number of the document and the product: for example, application version 1.5, version 1.3 of the documentation.

What is the general way / best practice for writing software documentation? Do you track document changes there? If you print a change history - are changes in the product and / or document displayed?

+6
version-control versioning documentation
source share
4 answers

I think that documentation and software are different elements, each of which has different version numbers. You want to update the documentation without updating the software number. I would call it something like:

System Documentation for the ProductX 1.3

Documentation Version 1.7

Clearly, both the software version and the document version in the same place should not be confused.

+3
source share

We tend to use a simple text format for our documentation, mainly LaTeX, and treat it the same way as the source code from the point of view of revision: it goes to the repo, we can make differences and patches, etc. We are not big for the history of changes in published documents, we can always check what happened if necessary, but this rarely happens.

Regarding the synchronization of code version numbers and documentation, our preferred approach is that the document v1.1.1 corresponds to software v1.1.1, 3.2.45 corresponds to 3.2.45, etc. However, in practice, we often only have documentation for the first two digits (for example, 1.1, 3.2), since the third digit is mainly designed to correct errors or improve performance. The revo revision number is inserted into the documentation (and into the source code) using svn: keywords if we ever need to.

I would like to tell you that the same makefile that our new software creates also creates a new version of the documentation, but we have not received it yet. However, we are working on it.

+3
source share

I ran into this problem in every company I worked for, which 1) had a significant code base, 2) tried to get professional-quality documentation, and 3) had separate development and documentation groups.

I agreed with Anders, convinced that the software and documentation should have different version and version control systems. Although similar and having the same goal, the documentation and code have different life cycles that can be completely independent, are displayed only once at a different time of release.

As for creating documentation with every build of software, ask yourself: does this really make sense? Is the documentation historical or prescriptive? Any documentation created with each assembly has better tools for its implementation. Currently this only works for API documentation, and Doxygen / Javadoc tools exist to support this tool. This will probably never be feasible for the user guide and installation guide, as they are context sensitive.

The need for various version control systems is fulfilled, in particular, for new structured documentation methodologies. Structured documentation should be managed at a much finer level of detail than the source code in order to be able to efficiently process something even seemingly as simple as rebranding; usually controlled by either a paragraph, a sentence, or a word level, in contrast to the file level, which is enough for the source code. In addition, as a rule, it is economical that the elements of a document can be divided between several products or departments (design, marketing, etc.). And for this level of documentation complexity, only a content management system is enough to track content and manage changes; CVC- / SVN- / Perforce- / Clearcase-SCCS are incredibly inadequate for managing real documentation. Using different version control tools provides different version numbers for documentation and software.

Documentation can even have a higher rate of change than software when it considers the need to handle typos, grammar errors, and corporate identity changes.

Separation of documentation and development processes reduces dependence, which is the fundamental metric necessary to create a quality product. In addition, late binding is desirable to best take into account the fast pace of change and unpredictable events, such as late additions or deletions of functions. Only at the time of the final (or alpha / beta release) version of the documentation should be displayed on the software version. But I agree with the High-Performance Mark that the end user should not see different version numbers. The version number of the documentation should not appear in the document. This number may be maintained and hidden from the public during the documentation process.

The only time that software and documentation versions can be locked is when the documentation is a fully integrated part of the development process. Over the past 30 years, I have seen that this is getting smaller and smaller because there is a less formal, advanced design than before, relying instead on an iterative, fast prototype approach to software development. The initial good intentions regarding the development of documentation software were largely postponed, but the new methodology also did not give us improved documentation or software. Regardless of whether this documentation is done in advance or as an afterthought, it will still double the time it takes to develop a product of commercial quality.

+3
source share

Why don't you just use version control and use this as an automatic revision of a document? You can get most systems to update text when ordering.

0
source share

All Articles