Re: Revision histories in user docs

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On Thu, Oct 25, 2018 at 10:39 PM Petr Bokoc <pbokoc@xxxxxxxxxx> 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@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



-- 
Brian (bex) Exelbierd | bexelbie@xxxxxxxxxx | bex@xxxxxxxxx
Fedora Community Action & Impact Coordinator
@bexelbie | http://www.winglemeyer.org
_______________________________________________
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




[Index of Archives]     [Fedora Users]     [Fedora Desktop]     [Red Hat 9]     [Yosemite News]     [KDE Users]

  Powered by Linux