Alright, thank you for your thoughts, everyone.
I added some decent-ish revision histories to user docs (Install Guide
and Sysadmin Guide; Release Notes are almost completely rewritten for
each release so listing all changes doesn't make sense). I didn't do it
for F28 and earlier but changes in F29 are listed.
A few people mentioned a good point about encouraging meaningful commit
messages; when I finally get around to writing better contribution
guidelines I'll make sure to mention that.
Petr
On 10/25/18 10:39 PM, Petr Bokoc 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.org/archives/list/docs@lists.fedoraproject.org
--
Petr Bokoč (pbokoc)
Senior Technical Writer
Community Platform Engineering
Red Hat Czech, s. r. o.
Purkyňova 99
612 45 Brno, Czech Republic