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
On Tue, Jun 12, 2018 at 07:10:23PM +0200, Adam Samalik wrote:
** 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?
+1 do it!
Where do I file issues? We dropped this ("make sidebars really be sidebars") from the current setup and I really want it back. https://pagure.io/fedora-docs/docs-fp-o/c/18e04d74e1e2d99a23be8acd9237389ae8...
On Fri, Jun 15, 2018 at 6:36 PM Matthew Miller mattdm@fedoraproject.org wrote:
On Tue, Jun 12, 2018 at 07:10:23PM +0200, Adam Samalik wrote:
** 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?
+1 do it!
Where do I file issues? We dropped this ("make sidebars really be sidebars") from the current setup and I really want it back.
https://pagure.io/fedora-docs/docs-fp-o/c/18e04d74e1e2d99a23be8acd9237389ae8...
I think that the current issue tracker [1] with "Antora: ..." in the title would be the best place.
[1] https://pagure.io/fedora-docs/docs-fp-o/issues
-- Matthew Miller mattdm@fedoraproject.org Fedora Project Leader _______________________________________________ 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...
On Mon, Jun 18, 2018 at 07:40:22PM +0200, Adam Samalik wrote:
I think that the current issue tracker [1] with "Antora: ..." in the title would be the best place. [1] https://pagure.io/fedora-docs/docs-fp-o/issues
Done; thanks! https://pagure.io/fedora-docs/docs-fp-o/issue/78
On 06/12/2018 12:10 PM, Adam Samalik wrote:
- 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?
I'm late, but +1 to this plan too.
From the CommOps / sub-project POV, I would like to better know what changes I need to do to update our documentation. My understanding prior was that Antora would be a backend change and I would not have to make adjustments to our docs. It's fine if we need to make changes, but I will be curious to know what is needed and how to do it, so I can set up documentation for other sub-projects waiting to move:
https://pagure.io/fedora-diversity/issue/61
Hey Justin,
There will be some slight changed to the source repo, too. But don't worry, no format changes (it's still asciidoc), just the structure and the definition of the menu on the left will be a bit different. I'll prepare materials with all the info needed for you to switch. Also happy to assist.
Adam
On Fri, Jun 29, 2018 at 9:38 PM Justin W. Flory jflory7@gmail.com wrote:
On 06/12/2018 12:10 PM, Adam Samalik wrote:
- 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?
I'm late, but +1 to this plan too.
From the CommOps / sub-project POV, I would like to better know what changes I need to do to update our documentation. My understanding prior was that Antora would be a backend change and I would not have to make adjustments to our docs. It's fine if we need to make changes, but I will be curious to know what is needed and how to do it, so I can set up documentation for other sub-projects waiting to move:
https://pagure.io/fedora-diversity/issue/61-- Cheers, Justin W. Flory jflory7@gmail.com
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...
On 07/03/2018 03:19 AM, Adam Samalik wrote:
Hey Justin,
There will be some slight changed to the source repo, too. But don't worry, no format changes (it's still asciidoc), just the structure and the definition of the menu on the left will be a bit different. I'll prepare materials with all the info needed for you to switch. Also happy to assist.
Sounds good to me. Just so I make sure I actually learn and understand what I'm doing, I want to get a grip for what's going on and what the best practices are. Once there are resources in place for this, please let us know on the list. :-)
I've made a template repo here: (note the antora branch)
https://pagure.io/fedora-docs/template/branch/antora
On Tue, Jul 17, 2018 at 2:32 AM Justin W. Flory jflory7@gmail.com wrote:
On 07/03/2018 03:19 AM, Adam Samalik wrote:
Hey Justin,
There will be some slight changed to the source repo, too. But don't worry, no format changes (it's still asciidoc), just the structure and the definition of the menu on the left will be a bit different. I'll prepare materials with all the info needed for you to switch. Also happy to assist.
Sounds good to me. Just so I make sure I actually learn and understand what I'm doing, I want to get a grip for what's going on and what the best practices are. Once there are resources in place for this, please let us know on the list. :-)
-- Cheers, Justin W. Flory jflory7@gmail.com
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...
I ran into some issues while editing the *.adocs on my own system.My method had several steps. clone a specific git repository use the script below to create the local html output via firefox.copy the firefox output to libreoffice.Edit the libreoffice file for grammar, using standard review tools. After edit, transfer the LibreOffice review tool changes to the corresponding *.adoc file.
For what it is worth, here is the script that I wrote and used.
#!/bin/bash # adoc.sh April 2018 # if [ $# = 0 ]; then echo "command is $0 AnAdocFile.adoc " echo "output to /tmp/asciidoc.html " echo "Also creates a /tmp/x.sh pointing vim to the AnAdocFile.adoc" exit 0 fi bn=$(basename $1 .adoc) dn=$(pwd) inadoc=${bn}.adoc asciidoctor -o /tmp/${bn}.html ${bn}.adoc 2>/tmp/${bn}.errs firefox /tmp/${bn}.html echo "vim ${dn}/$inadoc " >/tmp/x.sh chmod 755 /tmp/x.sh clear ls -l #
The adoc file that I needed to match to the LO output was available via /tmp/x.sh What is the advantage of proofing with LO writer? Ans.Markups are visible and available for review by multiple other parties. (collaboration)
Difficulties encountered. The adoc files were unraveled. That is, from the git repository, a single text line represents represents a paragraph. Matching LO markup to the adoc files necessitated the above approach
Other comments.I would like the *.adoc tools (asciidoctor) to be entirely available within rpmfusion.
Regards Leslie Leslie Satenstein Montréal Québec, Canada
On Tuesday, July 17, 2018, 2:54:46 a.m. EDT, Adam Samalik asamalik@redhat.com wrote:
I've made a template repo here: (note the antora branch) https://pagure.io/fedora-docs/template/branch/antora On Tue, Jul 17, 2018 at 2:32 AM Justin W. Flory jflory7@gmail.com wrote:
On 07/03/2018 03:19 AM, Adam Samalik wrote:
Hey Justin,
There will be some slight changed to the source repo, too. But don't worry, no format changes (it's still asciidoc), just the structure and the definition of the menu on the left will be a bit different. I'll prepare materials with all the info needed for you to switch. Also happy to assist.
Sounds good to me. Just so I make sure I actually learn and understand what I'm doing, I want to get a grip for what's going on and what the best practices are. Once there are resources in place for this, please let us know on the list. :-)
On Wed, Aug 15, 2018 at 7:48 AM, Leslie S Satenstein lsatenstein@yahoo.com wrote:
I ran into some issues while editing the *.adocs on my own system. My method had several steps.
clone a specific git repository use the script below to create the local html output via firefox. copy the firefox output to libreoffice. Edit the libreoffice file for grammar, using standard *review* tools. After edit, transfer the LibreOffice review tool changes to the corresponding *.adoc file.
For what it is worth, here is the script that I wrote and used.
*#!/bin/bash* *# adoc.sh April 2018* *#* *if [ $# = 0 ];* *then*
- echo "command is $0 AnAdocFile.adoc "*
- echo "output to /tmp/asciidoc.html "*
- echo "Also creates a /tmp/x.sh pointing vim to the AnAdocFile.adoc"*
- exit 0*
*fi* *bn=$(basename $1 .adoc)* *dn=$(pwd)* *inadoc=${bn}.adoc* *asciidoctor -o /tmp/${bn}.html ${bn}.adoc 2>/tmp/${bn}.errs* *firefox /tmp/${bn}.html* *echo "vim ${dn}/$inadoc " >/tmp/x.sh* *chmod 755 /tmp/x.sh* *clear* *ls -l* *#*
The adoc file that I needed to match to the LO output was available via /tmp/x.sh
What is the advantage of proofing with LO writer? Ans.Markups are visible and available for review by multiple other parties. (collaboration)
Difficulties encountered. The adoc files were unraveled. That is, from the git repository, a single text line represents represents a paragraph. Matching LO markup to the adoc files necessitated the above approach
In the .adoc files we are working to changing to single line == single sentence structure. This makes diffs much cleaner.
Other comments. I would like the *.adoc tools (asciidoctor) to be entirely available within rpmfusion.
You'll need to take this up with the folks at rpmfusion.
I encourage you to use the asciidoctor that is packaged in Fedora instead. Antora is not yet packaged, but will be soon, however, if you use the suggested docker containers you won't need it.
regards,
bex
Regards
- Leslie*
*Leslie Satenstein* *Montréal Québec, Canada*
On Tuesday, July 17, 2018, 2:54:46 a.m. EDT, Adam Samalik < asamalik@redhat.com> wrote:
I've made a template repo here: (note the antora branch)
https://pagure.io/fedora-docs/template/branch/antora
On Tue, Jul 17, 2018 at 2:32 AM Justin W. Flory jflory7@gmail.com wrote:
On 07/03/2018 03:19 AM, Adam Samalik wrote:
Hey Justin,
There will be some slight changed to the source repo, too. But don't worry, no format changes (it's still asciidoc), just the structure and the definition of the menu on the left will be a bit different. I'll prepare materials with all the info needed for you to switch. Also happy to assist.
Sounds good to me. Just so I make sure I actually learn and understand what I'm doing, I want to get a grip for what's going on and what the best practices are. Once there are resources in place for this, please let us know on the list. :-)
-- Cheers, Justin W. Flory jflory7@gmail.com
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/message/EJ7RNTIIB4J46Z4SW4PJPINBENSOHP4K/
--
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/message/N3XZGIXJCRVTYQ6KG6TKXM6DH5QZIV3O/
-
Adam Samalik -
Brian (bex) Exelbierd -
Justin W. Flory -
Leslie S Satenstein -
Matthew Miller