6

In addition to this question Should Git be used for documentation and project management? Should the code be in a separate repository? I want to ask if it is recommended to keep the documentation version (e.g.: for a REST API) the same as project version, assuming the code and documentation are in the same git repository.

So this means that if changes are submitted in project code and the project version will increment, the documentation version will also increment, even if there isn't any change in the documentation.

What would be the advantages and disadvantages of this practice?

I am asking this because I want the documentation (in my case the documentation is generated using apidocjs from code comments of a node.js project) to copy automatically the version from the project settings (package.json). This will simplify the documentation versioning, because I don't have to remember to update it, so it will always be in sync with the code.

I know this question is subjective but I couldn't find anywhere a clarification on this.

Alexandru Irimiea
  • 169
  • 2

2 Answers2

4

To keep the documentation version the same as project version

is not documentation versioning. It merely states "the documentation was extracted with that software version".

Of course it has a benefit that user can always easily check that document version matches software version and get updated one when don't.

Big drawback of doing so with your documentation (or API) is that you do not provide users with information if it is any different from the previous one. When you increment version of your software you do it exactly to indicate a change. Users will discover soon that incremented document version does not mean updated content and would be resilient to check for new versions.

In the real life documentation (and, again, API) does not change with each tiny software version, especially if you have several types and levels of it. Distinguish different document attributes

  • its own version
  • versions of software to which it applies (often only 'from' version)
  • version of software with which it was bundled
Vlad
  • 559
  • 1
  • 3
  • 6
1

If the documentation is auto-generated from the code, there's no need to store it under version control at all - in the same way that you don't need to store compiled code under VC. You just need to store any scripts or tool settings files required to generate the documentation from the code. The user can re-generate the documentation on the fly, perhaps as part of the build process.

Simon B
  • 9,167
  • 4
  • 26
  • 33
  • I don't store the generated documentation on git - I store only the scripts necessary to generate it. My question was about using the project version when generating a new version of documentation. – Alexandru Irimiea Apr 06 '17 at 08:39