docs October 2018

docs@lists.fedoraproject.org

18 participants
21 discussions

Revision histories in user docs
by Petr Bokoc 07 Nov '18

07 Nov '18

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 5

Fedora 29 Docs are published
by Adam Samalik 30 Oct '18

30 Oct '18

I've just published Fedora 29 Docs — will be visible very soon: https://docs.fedoraproject.org/en-US/docs/ Thanks everyone who contributed, especially Petr Bokoc! Cheers, Adam -- Adam Šamalík --------------------------- Software Engineer Red Hat

3 2

[Fedocal] Reminder meeting : Fedora Docs Weekly Meeting
by bex＠fedoraproject.org 30 Oct '18

30 Oct '18

Dear all, You are kindly invited to the meeting: Fedora Docs Weekly Meeting on 2018-10-31 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://fedoraproject… Source: https://apps.fedoraproject.org/calendar/meeting/9196/

1 0

Translations are coming!
by Adam Samalik 30 Oct '18

30 Oct '18

Hey everyone, I had some discussions about translations with a few people and this is the result: We have a new epic [1] tracking the initial implementation. The English pipeline is quite straightforward — it takes the English source and converts it into the English site. That already works today. Simplified view: `English source -> English site` The translation pipeline has a few more steps. First, we need to have a script that converts the English sources to POT files [#114] which are used for translations. These POT files need to be stored in a git repository [#110] [#111] and will be consumed by a translation engine which pushes the results back into the repo. To make it consumable for Antora, we need another script that converts the resulting PO files into translated sources [#115] and store them [#112] [#113] somewhere. Before the site can be built, we also need to have a translated UI for each language that also has a language switcher [#116] [#117]. The UI along with the translated sources will be consumed by a build script [#119] that builds the final website. Simplified view: `English source -> POT files -> PO files -> translated source -> translated site` Apart from these, we also need to have two new policies. One for adding new content to the docs [#120] which need to ensure that the new content is also being translated properly. The other one will be about introducing a new language [#121] and will make sure that all the repositories are set up and that the UI also supports this new language. Last thing is the "edit this page" button on translated sites. For that, we probably need to have a page for each language explaining that the content is created and edited in English, and how translations work and how to contribute. And the "edit this page" link (with likely a different wording) will point to that page. There are no cards for this, yet. So, we need places to store: * POT + PO files for every language [#110] [#111] * translated sources for every language [#112] [#113] We needs scripts for: * Converting English sources to POT files [#114] * Converting PO files to translated sources for every language [#115] * Converting translated sources + translated UI to the translated site for every language [#119] And we also need: * Translated UI for every language [#116] [#117] * Policy for adding new content to the docs that ensures adding it also to translations [#120] * Policy for introducing a new language [#121] As you can see, the implementation will be "translation engine-agnostic" — using POT and PO files. This way we can have some flexibility. I'll start working on it later this week. If you have any feedback or want to help, let me know! Cheers! Adam [1] https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/epic/1 [#110] https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/110 [#111] https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/111 [#112] https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/112 [#113] https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/113 [#114] https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/114 [#115] https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/115 [#116] https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/116 [#117] https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/117 [#118] https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/118 [#119] https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/119 [#120] https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/120 [#121] https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/us/121 -- Adam Šamalík --------------------------- Software Engineer Red Hat

6 8

we need better spin/remix howto documention
by Matthew Miller 29 Oct '18

29 Oct '18

I wanted to answer https://www.reddit.com/r/linux/comments/9q3b9v/custom_linux_distro_based_on… with an easy "well, I don't know about Debian, but here's how you do it for Fedora"... but it turns out we don't have a great page I can just link to. https://fedoraproject.org/wiki/Infrastructure/CustomSpins is both out of date and short on specifics, and https://fedoraproject.org/wiki/Remix is too high level. Our mission is meant to accommodate and encourage this. We should explain better how to actually do it. Any volunteers? -- Matthew Miller <mattdm(a)fedoraproject.org> Fedora Project Leader

6 15

[Fedocal] Reminder meeting : Docs Writing Hour
by pbokoc＠fedoraproject.org 29 Oct '18

29 Oct '18

Dear all, You are kindly invited to the meeting: Docs Writing Hour on 2018-10-31 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/

1 0

[Fedocal] Reminder meeting : Fedora Docs Weekly Meeting
by bex＠fedoraproject.org 23 Oct '18

23 Oct '18

Dear all, You are kindly invited to the meeting: Fedora Docs Weekly Meeting on 2018-10-24 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://fedoraproject… Source: https://apps.fedoraproject.org/calendar/meeting/9196/

1 0

[Fedocal] Reminder meeting : Docs Writing Hour
by pbokoc＠fedoraproject.org 22 Oct '18

22 Oct '18

Dear all, You are kindly invited to the meeting: Docs Writing Hour on 2018-10-24 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/

1 0

Fedora 29 Final Release Readiness meeting
by Ben Cotton 17 Oct '18

17 Oct '18

Dear all, Join us on irc.freenode.net in #fedora-meeting-1 for the Fedora 29 Final Release Readiness meeting. This meeting will be held on Thursday, 2018-10-18 at 19:00 UTC. We will meet to make sure we are coordinated and ready for the Final release of Fedora 29. Please note that this meeting will be held even if the release is delayed at the Go/No-Go meeting on the same day two hours earlier. You may receive this message several times in order to open this meeting to the teams and to raise awareness, so hopefully more team representatives will come to this meeting. This meeting works best when we have representatives from all of the teams. For more information, see https://fedoraproject.org/wiki/Release_Readiness_Meetings. View the meeting on Fedocal: https://apps.fedoraproject.org/calendar/Fedora%20release/2018/10/18/#m9380 -- Ben Cotton Fedora Program Manager TZ=America/Indiana/Indianapolis

1 1

[Fedocal] Reminder meeting : Fedora Docs Weekly Meeting
by bex＠fedoraproject.org 16 Oct '18

16 Oct '18

Dear all, You are kindly invited to the meeting: Fedora Docs Weekly Meeting on 2018-10-17 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://fedoraproject… Source: https://apps.fedoraproject.org/calendar/meeting/9196/

1 0

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

2007

2006

2005

2004

2003

2002

docs October 2018