Hi Leslie,
That's right, we are working on introducing a new build mechanism for the Fedora Docs. The source format will still be asciidoc, the only thing that changes is how the files will be structured in the Pagure repository.
To your second point, I think the best would be to let the owners of the docs know, and coordinate with them submitting your changes as a pull request to Pagure. Do you have it somewhere to preview? I think sending it to the list docs@lists.fedoraproject.org could be a good start.
If you would like to help us with testing the new site or converting existing content, that would be great. If you want to have a look at the sources, see https://pagure.io/fork/bex/fedora-docs/docs-fp-o/tree/antora_playbook — it should have all the instructions to build the site, as well as links to other repositories where the content source (asciidoc files) live.
Thanks, Adam
On Tue, Jun 12, 2018 at 7:36 PM Leslie S Satenstein lsatenstein@yahoo.com wrote:
Hi Adam
I am new to the docs project. I am trying to understand your message. Are you saying that there will be a new tool, Antora (I did visit the website) and it is a way to provide a document management facility.
*Related topic.*
About 6 weeks ago, I pasted 3 Fedora docs into LibreOffice. My intent was to mark them up, for grammar and sentence construction, using standard industry markup tools.
I used LibreOffice, and want to backport the LO corrections to asciidoc. My markup corrections are in Canadian English with US spelling, given Fedora's roots.
My 80 hours of efforts are waiting for a "proof reader" partner who would do a accept/reject of each markup, using the easy to use LibreOffice tools. From there I would backport the corrected text. The backport, I understand would be a PR, or another type of asciidoc submission.
Of importance, I have a marked up 3 guides: admin guide, release guide, and install guide.
My markups, if accepted in their entirety would be a "better read" and should offer better comprehension than the existing docs I cloned from the Fedora Docs website.
So far I have not been able to clone the existing asciidoc files. Is this what Antora is about, allowing one submit new docs and/or to clone and submit corrections?
Do you need help to test. I am available almost 30hrs/week, (I am retired after 55 years in IT, As a retirement activity I develop Linux software in C/C++ or other fanciful languages. I also do blog write)
Regards
- Leslie*
*Leslie Satenstein* *Montréal Québec, Canada*
*From:* Adam Samalik asamalik@redhat.com *To:* For participants of the Documentation Project < docs@lists.fedoraproject.org> *Cc:* Brian Exelbierd bexelbie@redhat.com *Sent:* Tuesday, June 12, 2018 1:10 PM *Subject:* Antora for Docs: making sure our contributors are on board
As many of you have probably noticed, together with bex and few other people I work on moving the Fedora Docs to Antora. It has many technical benefits as well as an active community. Talking about community, I want to make sure that when the time comes and we're ready to push this thing to production, our contributors are on board.
So I've just created a new epic: People! [1]
"The main reason we go through all this trouble is people. We want to make it simple for people to contribute to the docs. And might not be a bad idea to make sure our contributors are on board when we go crazy and push this thing to production."
I'm looking for any useful input about making sure our contributors are on board. I want this to be as smooth as possible.
My thinking is:
- Announce it here on this very list.
- Contact in advance every group having their docs on the site and:
** making sure we have converted their asciibinder source into the Antora source right ** making sure they know how to make changes
- Do this over a few days, switching the Antora branches in all
repositories the site is built from to be the main branches. During these few days, the current asciibinder site wouldn't update. All updates from this period would end up on the new site. Basically, doing a few-days-log freeze.
How does that sound? Anything I've missed?
Thanks! Adam
[1] https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/epic/58
--
Adam Šamalík
Software Engineer Red Hat _______________________________________________ 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/m...
Hi Adam I had some coaching with Bex concerning a clone of the admin guide. I have a local copy. I have reviewed my markups to the admin guide and I am in the process of backporting the LibreOffice markups to the correspondig asciidoc file.So far it is going well. I've made mainly grammatical corrections spelling, commas, double "the the" and so forth. In some cases a long sentence was split into two for clarity. I will be on vacation beginning tomorrow (June 19 for 8 days). Thereafter, I will complete the backporting of the changes. Following my review, I will request prs for each.
Thus far, these are the *adocs that I have changed for the better. repositories/install-guide/en-US entities.adoc Revision History
repositories/install-guide/en-US/advanced Boot_Options.adoc Kickstart_Installations.adoc Network_based_Installations.adoc VNC_Installations.adoc Upgrading_Your_Current_System.adoc
repositories/install-guide/en-US/install After_Installation.adoc Booting_the_Installation.adoc CustomSpoke_AddBtrfs.adoc CustomSpoke_AddLVM.adoc CustomSpoke_AddPhysical.adoc CustomSpoke_FileSystem.adoc CustomSpoke.adoc DateTimeSpoke.adoc WelcomeSpoke.adoc UserSpoke.adoc
Progress speed is between that of a snail's and a turtle. Regards Leslie Leslie Satenstein Montréal Québec, Canada
From: Adam Samalik asamalik@redhat.com To: lsatenstein@yahoo.com Cc: Brian Exelbierd bexelbie@redhat.com; For participants of the Documentation Project docs@lists.fedoraproject.org Sent: Monday, June 18, 2018 1:38 PM Subject: Re: Antora for Docs: making sure our contributors are on board
Hi Leslie, That's right, we are working on introducing a new build mechanism for the Fedora Docs. The source format will still be asciidoc, the only thing that changes is how the files will be structured in the Pagure repository. To your second point, I think the best would be to let the owners of the docs know, and coordinate with them submitting your changes as a pull request to Pagure. Do you have it somewhere to preview? I think sending it to the list docs@lists.fedoraproject.org could be a good start. If you would like to help us with testing the new site or converting existing content, that would be great. If you want to have a look at the sources, see https://pagure.io/fork/bex/fedora-docs/docs-fp-o/tree/antora_playbook — it should have all the instructions to build the site, as well as links to other repositories where the content source (asciidoc files) live. Thanks,Adam On Tue, Jun 12, 2018 at 7:36 PM Leslie S Satenstein lsatenstein@yahoo.com wrote:
Hi Adam I am new to the docs project. I am trying to understand your message. Are you saying that there will be a new tool, Antora (I did visit the website) and it is a way to provide a document management facility.
Related topic.============ About 6 weeks ago, I pasted 3 Fedora docs into LibreOffice. My intent was to mark them up, for grammar and sentence construction, using standard industry markup tools. I used LibreOffice, and want to backport the LO corrections to asciidoc. My markup corrections are in Canadian English with US spelling, given Fedora's roots.
My 80 hours of efforts are waiting for a "proof reader" partner who would do a accept/reject of each markup, using the easy to use LibreOffice tools. From there I would backport the corrected text. The backport, I understand would be a PR, or another type of asciidoc submission. Of importance, I have a marked up 3 guides: admin guide, release guide, and install guide. My markups, if accepted in their entirety would be a "better read" and should offer better comprehension than the existing docs I cloned from the Fedora Docs website.
So far I have not been able to clone the existing asciidoc files. Is this what Antora is about, allowing one submit new docs and/or to clone and submit corrections? Do you need help to test. I am available almost 30hrs/week, (I am retired after 55 years in IT, As a retirement activity I develop Linux software in C/C++ or other fanciful languages. I also do blog write) Regards Leslie Leslie Satenstein Montréal Québec, Canada
From: Adam Samalik asamalik@redhat.com To: For participants of the Documentation Project docs@lists.fedoraproject.org Cc: Brian Exelbierd bexelbie@redhat.com Sent: Tuesday, June 12, 2018 1:10 PM Subject: Antora for Docs: making sure our contributors are on board
As many of you have probably noticed, together with bex and few other people I work on moving the Fedora Docs to Antora. It has many technical benefits as well as an active community. Talking about community, I want to make sure that when the time comes and we're ready to push this thing to production, our contributors are on board. So I've just created a new epic: People! [1]
"The main reason we go through all this trouble is people. We want to make it simple for people to contribute to the docs. And might not be a bad idea to make sure our contributors are on board when we go crazy and push this thing to production." I'm looking for any useful input about making sure our contributors are on board. I want this to be as smooth as possible. My thinking is: * Announce it here on this very list.* Contact in advance every group having their docs on the site and:** making sure we have converted their asciibinder source into the Antora source right** making sure they know how to make changes* Do this over a few days, switching the Antora branches in all repositories the site is built from to be the main branches. During these few days, the current asciibinder site wouldn't update. All updates from this period would end up on the new site. Basically, doing a few-days-log freeze. How does that sound? Anything I've missed? Thanks!Adam [1] https://taiga.fedorainfracloud.org/project/asamalik-antora-for-docs/epic/58