Antora for Docs: making sure our contributors are on board

[Adam Samalik]

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

[Matthew Miller]

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/18e04d74e1e2d99a23be8acd9237389...

-- 
Matthew Miller
<mattdm(a)fedoraproject.org&gt;
Fedora Project Leader

[Adam Samalik]

On Fri, Jun 15, 2018 at 6:36 PM Matthew Miller <mattdm(a)fedoraproject.org&gt;
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/18e04d74e1e2d99a23be8acd9237389...

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(a)fedoraproject.org&gt;
>  Fedora Project Leader
>  _______________________________________________
>  docs mailing list -- docs(a)lists.fedoraproject.org
>  To unsubscribe send an email to docs-leave(a)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/[e-mail]...
>  

-- 

Adam Šamalík
---------------------------
Software Engineer
Red Hat

[Matthew Miller]

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

-- 
Matthew Miller
<mattdm(a)fedoraproject.org&gt;
Fedora Project Leader

[Justin W. Flory]

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(a)gmail.com

[Adam Samalik]

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(a)gmail.com&gt; 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(a)gmail.com
>
>  _______________________________________________
>  docs mailing list -- docs(a)lists.fedoraproject.org
>  To unsubscribe send an email to docs-leave(a)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/[e-mail]...
>  

-- 

Adam Šamalík
---------------------------
Software Engineer
Red Hat

[Justin W. Flory]

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(a)gmail.com

[Adam Samalik]

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(a)gmail.com&gt; 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(a)gmail.com
>
>  _______________________________________________
>  docs mailing list -- docs(a)lists.fedoraproject.org
>  To unsubscribe send an email to docs-leave(a)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/[e-mail]...
>  

-- 

Adam Šamalík
---------------------------
Software Engineer
Red Hat

[Leslie S Satenstein]

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(a)redhat.com&gt;
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(a)gmail.com&gt; 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(a)gmail.com

_______________________________________________
docs mailing list -- docs(a)lists.fedoraproject.org
To unsubscribe send an email to docs-leave(a)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/[e-mail]...



-- 

Adam Šamalík
---------------------------
Software Engineer
Red Hat
_______________________________________________
docs mailing list -- docs(a)lists.fedoraproject.org
To unsubscribe send an email to docs-leave(a)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/[e-mail]...

[Brian (bex) Exelbierd]

On Wed, Aug 15, 2018 at 7:48 AM, Leslie S Satenstein <lsatenstein(a)yahoo.com&gt;
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(a)redhat.com&gt; 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(a)gmail.com&gt; 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(a)gmail.com
>
>  _______________________________________________
>  docs mailing list -- docs(a)lists.fedoraproject.org
>  To unsubscribe send an email to docs-leave(a)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(a)lists.fedoraproject.org
>  To unsubscribe send an email to docs-leave(a)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/
>  


-- 
Brian (bex) Exelbierd | bexelbie(a)redhat.com | bex(a)pobox.com
Fedora Community Action & Impact Coordinator
@bexelbie | http://www.winglemeyer.org