I would suggest three sections of the document is to be a living one. By living, not frozen from changelog until the next release.
On Mon, 29 Oct 2018 at 1:44 PM, Brian (bex) Exelbierd<bexelbie@redhat.com> wrote:On Thu, Oct 25, 2018 at 10:39 PM Petr Bokoc <pbokoc@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.
How about a hybrid here of encouraging good git commits, ideally with
the merger pushing back if they are just "changed stuff." I realize
that puts a lot of work on you Petr, so I deliberately say
"encourage."
> * Just get rid of revision histories altogether. We'd lose a potentially
> useful feature but in its current state it's useless anyway.
+1
> 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.
I'd like a last updated timestamp if we can get it. Can we Adam?
regards,
bex
>
> What do you all think?
>
> Petr
> _______________________________________________
> docs mailing list -- docs@lists.fedoraproject.org
> To unsubscribe send an email to docs-leave@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
--
Brian (bex) Exelbierd | bexelbie@redhat.com | bex@pobox.com
Fedora Community Action & Impact Coordinator
@bexelbie | http://www.winglemeyer.org
_______________________________________________
docs mailing list -- docs@lists.fedoraproject.org
To unsubscribe send an email to docs-leave@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