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@xxxxxxxxxxxxxxxxxxxxxxx > To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx > 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@xxxxxxxxxxxxxxxxxxxxxxx -- Petr Bokoč (pbokoc) Senior Technical Writer Community Platform Engineering Red Hat Czech, s. r. o. Purkyňova 99 612 45 Brno, Czech Republic _______________________________________________ docs mailing list -- docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx 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@xxxxxxxxxxxxxxxxxxxxxxx
