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
Something we’ve done for a few releases is to, just before docs freeze, update all revision histories with a list of major changes that affect that book. I think this provides useful information, but it’s not a regular part of our process day to day, so it does run the risk of being missed if we aren’t careful.
Cheers, Laura B
On Friday, October 26, 2018, 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.
- 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@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.or g/archives/list/docs@lists.fedoraproject.org
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
I would suggest three sections of the document is to be a living one. By living, not frozen from changelog until the next release. 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
Sent from Yahoo Mail on Android
On Mon, 29 Oct 2018 at 1:44 PM, Brian (bex) Exelbierdbexelbie@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
Hi Petr!
I do think that we need to encourage everyone to make descriptive commit messages. Also many git beginners might not realize how much easier it becomes when --global core.editor is set to their editor of choice. Maybe we could provide contributors with a good git commit.template for fedora docs?
Could be a good idea to rename ''Revision History" to "Revision Notes" since it looks it only contains some short notes and only describe the most important changes. I think that time stamps are sufficient there give some vague idea on how the work has progressed. For more we could link to pagure commits and everyone that is interested enough would find the changes there.
We need some proper Revision standards. What I mean is some sort of definitions on changes that are considered to be major,minor and so on. I wrote about it in regard to workflow and pdfs but the same could also apply to general docs writing https://pagure.io/fedora-docs/template/issue/5#comment-532233
For example if chapters are added, pages get renamed, content is moved or images changed - all this could be a good thing to standardize. I know that defining such Revision Notes Standards and adherence to it in itself could be a lot of work (so it's best to keep it simple), but it would show that we care about the quality of the docs.
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@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
docs@lists.stg.fedoraproject.org
-
Brian (bex) Exelbierd -
Gleb Vassiljev -
Laura Bailey -
Leslie S Satenstein -
Petr Bokoc