1) changes in this current section asthey occur.
2) changes from the previous release to the current Fedora release date.
3) changes implemented that were outstanding from older than the previous release. Can cover up to 3 or 4 releases back
One page max for each of 2) and 3)
Document engineering changes, not trivial ones for the older two
On Mon, 29 Oct 2018 at 1:44 PM, Brian (bex) Exelbierd<bexelbie@xxxxxxxxxx> wrote: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
_______________________________________________ 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
