search

redhat-documentation / modular-docs

Modular Documentation Project provides guidelines and examples for writing technical documentation using a modular framework.
Creative Commons Attribution Share Alike 4.0 International
82 stars 68 forks source link

Start versioning the templates #152

Closed Levi-Leah closed 2 years ago

Levi-Leah commented 3 years ago

The immediate benefits: peer reviewers will immediately see or get a strong hint if somebody is not using up-to-date template. If a major change is introduced to a template, it will also allow us to quickly have an idea what modules are likely in need of an update without having to use too much of regular expression magic.

rolfedh commented 3 years ago

This looks like a duplicate of https://github.com/redhat-documentation/modular-docs/issues/127. Would you mind if we close this one?

jhradilek commented 3 years ago

I would suggest adopting similar approach to Ubuntu for versioning and including a code for the origin of the template too. So for a template published on January 28, 2021 and generated by newdoc, something like the following:

// ver: 21.01.28-nd

I would also recommend placing it to a predictable place near the top of the template, perhaps even on the first line.

We keep running into situations where we are not certain how certain things got into our product documentation source code. Having a version like this would make it easier to trace where certain things come from and how they got in. The reason why I prefer this format over traditional version numbers and insist on including a code for the tool is that without further documentation in the form of a ChangeLog, the traditional version number holds very little information on its own. By adopting a versioning scheme similar to what I am suggesting, we would maximize the usefulness of having a version in the template.

thatdocslady commented 3 years ago

This looks like a duplicate of #127. Would you mind if we close this one?

+1, recommend to close this one and continue tracking in the other one.

emmurphy1 commented 2 years ago

Closing to continue the discussion in https://github.com/redhat-documentation/modular-docs/issues/127.