Revision histories in user docs
by Petr Bokoc
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
5 years, 5 months
- 5
- 5
[Fedocal] Reminder meeting : Fedora Docs Weekly Meeting
by bex＠fedoraproject.org
Dear all,
You are kindly invited to the meeting:
Fedora Docs Weekly Meeting on 2018-11-07 from 15:30:00 to 16:00:00 UTC
At fedora-meeting(a)irc.freenode.net
The meeting will be about:
An hour of docs folks talking about what they are working on and what they'd like to work on.
More information available at:
[https://fedoraproject.org/wiki/Docs_Project_meetings](https://fedoraproje...
Source: https://apps.fedoraproject.org/calendar/meeting/9196/
5 years, 5 months
- 1
- 0
[Fedocal] Reminder meeting : Docs Writing Hour
by pbokoc＠fedoraproject.org
Dear all,
You are kindly invited to the meeting:
Docs Writing Hour on 2018-11-07 from 10:00:00 to 11:00:00 US/Eastern
The meeting will be about:
Join members of the docs team in #fedora-docs for writing time. This is a great time to focus on writing and talk about challenges and blockers related to producing content.
There is no formal schedule for this meeting. Attendees should show up and use this as a way to block writing time into their week.
Source: https://apps.fedoraproject.org/calendar/meeting/9360/
5 years, 5 months
- 1
- 0