Something we’ve done for a few releases is to, just before docs freeze,
update all revision histories with a list of major changes that affect that
book. I think this provides useful information, but it’s not a regular part
of our process day to day, so it does run the risk of being missed if we
aren’t careful.
Cheers,
Laura B
On Friday, October 26, 2018, Petr Bokoc <pbokoc(a)redhat.com> wrote:
Hi docs,
For the longest time we used to maintain a revision history for each book
we published on docs.fp.o. However, they weren't particularly useful, each
revision was noted by the date, author, and an unhelpful note like
"updating for Fedora 21" or "async update", without a list of
specific
changes made. The revisions were basically only added because the old
toolchain used for Red Hat docs required it, and contributors from Red Hat
built a habit of adding them and did it in Fedora as well.
The current books (Release Notes, Installation Guide, and System
Administrator's Guide) still have revision histories, but the Install Guide
and Sysadmin Guide have last entries from 2016 and 2017 and the Release
Notes have an empty one (which makes sense since we completely rewrite the
book for each release, but I don't think people add new entries if they
republish). It's more confusing than useful at this point, and I think we
should do something about it.
The way I see it, we have two choices:
* Start maintaining proper revision histories with much more detail. This
would require every PR or commit to also add something to the revision
history, which means another thing to keep in mind and a little bit of
extra work. There's also a potential problem about the date: when you add a
revhistory entry, you have no way of knowing when it's actually going to be
published, so you have to use the current date - but the reader doesn't
care about when you commited it, the only use for a date in a revhistory is
for the reader to see if anything changed since they last checked.
* Just get rid of revision histories altogether. We'd lose a potentially
useful feature but in its current state it's useless anyway.
A third way would be to automatically insert a "last modified" timestamp
in every page's top bar; the timestamp would ideally contain a link to a
set of commit diffs relevant to that page with dates. That seems difficult
to implement though, so I don't think that's an option - unless we could
insert that timestamp during the CI/CD process when we have one, I suppose.
What do you all think?
Petr
_______________________________________________
docs mailing list -- docs(a)lists.fedoraproject.org
To unsubscribe send an email to docs-leave(a)lists.fedoraproject.org
Fedora Code of Conduct:
https://getfedora.org/code-of-conduct.html
List Guidelines:
https://fedoraproject.org/wiki/Mailing_list_guidelines
List Archives:
https://lists.fedoraproject.or
g/archives/list/docs(a)lists.fedoraproject.org
--
Laura Bailey
Principal Technical Writer
Customer Content Services BNE