Proposal: Adopt an AsciiBinder Based ToolChain

[Brian Exelbierd]

Hi All,

I am sorry I missed yesterday's meeting, I am at a conference this week.

I have written a longish proposal
(http://www.winglemeyer.org/fedora_docs_proposal/latest/proposal/overview....)
about adopting an AsciiBinder toolchain.

I've tried to outline the challenges we have today and how I believe
this will get us a new documentation website and process quickly.  There
is a Proof of Concept included with details on how you can replicate my
work.

I'd like feedback and to discuss if we can move forward with this
proposal.  Can we please use email as travel will also prevent me from
attending next week's meeting.

regards,

bex

[Lailah]

Hello Bexelbie!

May I ask what conference?
As for the topic, I think AsciiBinder is a good proposal and I'm keen
to it.


Cheers,
Sylvia

On Tue, 2016-09-20 at 09:47 +0200, Brian Exelbierd wrote:
>  Hi All,
>  
>  > I am sorry I missed yesterday's meeting, I am at a conference this 
week.
>  
>  I have written a longish proposal
>  > (http://www.winglemeyer.org/fedora_docs_proposal/latest/proposal/over
view.html)
>  about adopting an AsciiBinder toolchain.
>  
>  I've tried to outline the challenges we have today and how I believe
>  > this will get us a new documentation website and process 
quickly.  There
>  > is a Proof of Concept included with details on how you can
> replicate 
my
>  work.
>  
>  I'd like feedback and to discuss if we can move forward with this
>  > proposal.  Can we please use email as travel will also prevent me 
from
>  attending next week's meeting.
>  
>  regards,
>  
>  bex
>  _______________________________________________
>  docs mailing list -- docs(a)lists.fedoraproject.org
>  To unsubscribe send an email to docs-leave(a)lists.fedoraproject.org

[Brian Exelbierd]

On Tue, Sep 20, 2016, at 10:15 AM, Sylvia wrote:
>  Hello Bexelbie!
>
>  May I ask what conference? 
I am at Write the Docs Europe.  This has actually allowed me to get
some addtional feedback from folks not in the Fedora Community on
this proposal.

regards,

bex

>  As for the topic, I think AsciiBinder is a good proposal and I'm
>  keen to it.
>
>
>  Cheers,
>  Sylvia
>
>
>  On Tue, 2016-09-20 at 09:47 +0200, Brian Exelbierd wrote:
> > Hi All,  I am sorry I missed yesterday's meeting, I am at a
> > conference this week.  I have written a longish proposal
> > (http://www.winglemeyer.org/fedora_docs_proposal/latest/proposal/overview....)
> > about adopting an AsciiBinder toolchain.  I've tried to outline the
> > challenges we have today and how I believe this will get us a new
> > documentation website and process quickly.  There is a Proof of
> > Concept included with details on how you can replicate my work.  I'd
> > like feedback and to discuss if we can move forward with this
> > proposal.  Can we please use email as travel will also prevent me
> > from attending next week's meeting.  regards,  bex
> > _______________________________________________ docs mailing list --
> > docs(a)lists.fedoraproject.org To unsubscribe send an email to docs-
> > leave(a)lists.fedoraproject.org
> >
>  _________________________________________________
>  docs mailing list -- docs(a)lists.fedoraproject.org
>  To unsubscribe send an email to docs-leave(a)lists.fedoraproject.org

[Lailah]

Hi!

I didn't know this conference, looks interesting.  Sadly, it's too far
to attend and maybe now is over.  What kind of feedback and from whom
you got, Bexelbie?


Cheers,
Sylvia

On Tue, 2016-09-20 at 16:58 +0200, Brian Exelbierd wrote:
>  On Tue, Sep 20, 2016, at 10:15 AM, Sylvia wrote:
>  
>  > 
>  > Hello Bexelbie!
>  > 
>  > 
>  > 
>  > May I ask what conference?
>  > 
>  
>  > > I am at Write the Docs Europe.  This has actually allowed me to get 
some
addtional feedback from folks not in the Fedora Community on
this proposal.
>  
>  
>  
>  regards,
>  
>  
>  
>  bex
>  
>  
>  
>  > > > As for the topic, I think AsciiBinder is a good proposal and I'm
keen to it.
>  > 
>  > 
>  > 
>  > 
>  > Cheers,
>  > 
>  > Sylvia
>  > 
>  > 
>  > 
>  > 
>  > 
>  > On Tue, 2016-09-20 at 09:47 +0200, Brian Exelbierd wrote:
>  > 
>  > > Hi All,
>  > > > > > I am sorry I missed yesterday's meeting, I am at a
> conference 
this week.
>  > > 
>  > > I have written a longish proposal
>  > > > > >
> (http://www.winglemeyer.org/fedora_docs_proposal/latest/proposal/ 
overview.html)
>  > > about adopting an AsciiBinder toolchain.
>  > > 
>  > > > > > I've tried to outline the challenges we have today and how I
believe
>  > > > > > this will get us a new documentation website
> and process 
quickly.  There
>  > > > > > is a Proof of Concept included with details
> on how you can 
replicate my
>  > > work.
>  > > 
>  > > I'd like feedback and to discuss if we can move forward with this
>  > > > > > proposal.  Can we please use email as travel will also prevent
> me 
from
>  > > attending next week's meeting.
>  > > 
>  > > regards,
>  > > 
>  > > bex
>  > > _______________________________________________
>  > > docs mailing list -- docs(a)lists.fedoraproject.org
>  > > > > > To unsubscribe send an email to
> docs-leave(a)lists.fedoraproject.or 
g
>  > > 
>  > _______________________________________________
>  > 
>  > docs mailing list -- docs(a)lists.fedoraproject.org
>  > 
>  > To unsubscribe send an email to docs-leave(a)lists.fedoraproject.org
>  > 
>  
>  
>  
>  _______________________________________________
>  docs mailing list -- docs(a)lists.fedoraproject.org
>  To unsubscribe send an email to docs-leave(a)lists.fedoraproject.org

[Brian Exelbierd]

On Wed, Sep 21, 2016, at 10:41 AM, Sylvia wrote:
>  Hi!
>
>  I didn't know this conference, looks interesting.  Sadly, it's too far
>  to attend and maybe now is over.  What kind of feedback and from whom
>  you got, Bexelbie? 
The conference was interesting.  The feedback on the proposal has
already been incorporated in it.

I am slowly posting my session notes here:
http://www.winglemeyer.org/technology/2016/09/20/wtd.html/

The conference should also post videos eventually.

regards.

bex

>  Cheers,
>  Sylvia
>
>
>  On Tue, 2016-09-20 at 16:58 +0200, Brian Exelbierd wrote:
> > On Tue, Sep 20, 2016, at 10:15 AM, Sylvia wrote:
> >>
> >> Hello Bexelbie!
> >>
> >> May I ask what conference?
> >
> > I am at Write the Docs Europe.  This has actually allowed me to get
> > some addtional feedback from folks not in the Fedora Community on
> > this proposal.
> >
> > regards,
> >
> > bex
> >
> >> As for the topic, I think AsciiBinder is a good proposal and I'm
> >> keen to it.
> >>
> >>
> >> Cheers,
> >> Sylvia
> >>
> >>
> >> On Tue, 2016-09-20 at 09:47 +0200, Brian Exelbierd wrote:
> >>> Hi All,  I am sorry I missed yesterday's meeting, I am at a
> >>> conference this week.  I have written a longish proposal
> >>>
> (http://www.winglemeyer.org/fedora_docs_proposal/latest/proposal/overview....)
> >>> about adopting an AsciiBinder toolchain.  I've tried to outline the
> >>> challenges we have today and how I believe this will get us a new
> >>> documentation website and process quickly.  There is a Proof of
> >>> Concept included with details on how you can replicate my work.
> >>> I'd like feedback and to discuss if we can move forward with this
> >>> proposal.  Can we please use email as travel will also prevent me
> >>> from attending next week's meeting.  regards,  bex
> >>> _______________________________________________ docs mailing list
> >>> -- docs(a)lists.fedoraproject.org To unsubscribe send an email to docs-
> >>> leave(a)lists.fedoraproject.org
> >>>
> >> _________________________________________________
> >> docs mailing list -- docs(a)lists.fedoraproject.org
> >> To unsubscribe send an email to docs-leave(a)lists.fedoraproject.org
> >
> > _______________________________________________ docs mailing list --
> > docs(a)lists.fedoraproject.org To unsubscribe send an email to docs-
> > leave(a)lists.fedoraproject.org
> >
>  _________________________________________________
>  docs mailing list -- docs(a)lists.fedoraproject.org
>  To unsubscribe send an email to docs-leave(a)lists.fedoraproject.org

[Jean-Baptiste]

Le 20/09/2016 à 09:47, Brian Exelbierd a écrit :
>  Hi All,
>
>  I am sorry I missed yesterday's meeting, I am at a conference this week.
>
>  I have written a longish proposal
>  (http://www.winglemeyer.org/fedora_docs_proposal/latest/proposal/overview....)
>  about adopting an AsciiBinder toolchain.
>
>  I've tried to outline the challenges we have today and how I believe
>  this will get us a new documentation website and process quickly.  There
>  is a Proof of Concept included with details on how you can replicate my
>  work.
>
>  I'd like feedback and to discuss if we can move forward with this
>  proposal.  Can we please use email as travel will also prevent me from
>  attending next week's meeting.
>
>  regards,
>
>  bex
>  _______________________________________________
>  docs mailing list -- docs(a)lists.fedoraproject.org
>  To unsubscribe send an email to docs-leave(a)lists.fedoraproject.org 
Hi Brian,

I do not understand, isn't Gnome community is going to move from Mallard 
to Pintail ?
The first tool has internationalization included http://help.gnome.org 
and the second will have it (soon?).

Is AsciiBinder able to handle it or will handle it ? You described in 
your documentation how to produce po files, but what about publishing 
process ?

po4all is a cool tool (AFAIK created by Debian french team), but will 
our user have a global localized experience ?
Easy jump from one language to another, automatic language selection 
from one do to another, jumping from page to page without loosing 
current language setting, multi-language based search, etc ?

Is there a need to move quickly to that tool instead of waiting (or 
helping) Pintail to reach this goal ?
If it can't make internationalized content in the coming month, can't we 
find a temporary work-around ?

I tried searching "Target" in https://docs.openshift.com/ it makes a 
google research and failed. It also suggest automatic translation from 
google... Not very motivating for translators ;)

I do not feel comfortable about this publishing tool, while at the same 
time, we had a good Proof of concept of Pintail at GUADEC. 
https://media.ccc.de/v/108-unconference-6
It may be just marketing, please tell me :)

Will you convert from docbook to asciidoc every documentation from 
Fedora 7 ? I remember someone saying this conversion isn't easy.

At last, did you plan a mechanism to make comments for translator ?
Dummy example with C file : 
https://github.com/hughsie/appstream-glib/blob/master/client/as-builder.c...

Anyway, to me, the most important is making 
update/publish/translate/publish processes easier and smoother.
The work you're doing is really needed and good. It can be this tool or 
another, but I just do not understand the move. Sorry for so big email!

-- 
Jean-Baptiste Holcroft

[Brian Exelbierd]

On Tue, Sep 20, 2016, at 08:50 PM, Jean-Baptiste Holcroft wrote:
>  Hi Brian,
>  
>  I do not understand, isn't Gnome community is going to move from Mallard 
>  to Pintail ? 
Pintail is a site builder.  Mallard is a markup language.

I know that pintail is being considered by Gnome for use as a site
builder.  I haven't seen the announcement about the adoption of it.  I
don't believe it is feature complete yet.  I also don't track Gnome so
if it was formally adopted as the path forward, I may have just not seen
the announcement.

>  The first tool has internationalization included
> http://help.gnome.org 
>  and the second will have it (soon?).
>  
>  Is AsciiBinder able to handle it or will handle it ? You described in 
>  your documentation how to produce po files, but what about publishing 
>  process ? 
That is covered in the Proof of Concept section.  In short, yes, you can
publish multiple languages today.

>  po4all is a cool tool (AFAIK created by Debian french team), but will
>
>  our user have a global localized experience ?
>  Easy jump from one language to another, automatic language selection 
>  from one do to another, jumping from page to page without loosing 
>  current language setting, multi-language based search, etc ? 
My expectation is that this will be able to be accomplished.  I haven't
included this in the example because I do not have mad CSS or JavaScript
skills, but I do not believe this will be a challenge.

One thing that I want to hear from the Translation Team is how they want
to handle untranslated and partially translated texts.

>  Is there a need to move quickly to that tool instead of waiting (or 
>  helping) Pintail to reach this goal ? 
In my opinion, yes.  We need to increase contribution and reboot the
docs.  DocBook has been identified as an impediment to contribution. 
This gets us off of DocBook and onto a publishing platform that can
handle it.

I have not seen a project plan or roadmap for pintail.  Pintail does not
seem to be attracting a community which means we are highly reliant on
Shaun to complete the work.  I am sure he is working very hard, however
he can't be expected to abandon all of his other responsibilities and
solve our use case problems first.

>  If it can't make internationalized content in the coming month,
> can't we 
>  find a temporary work-around ? 
It can produce internationalized content.  See the example please.

>  I tried searching "Target" in https://docs.openshift.com/
> it makes a 
>  google research and failed. It also suggest automatic translation from 
>  google... Not very motivating for translators ;) 
OpenShift chooses not to translate their documentation.  I encourage you
to have a conversation with their community about the value of
translations.

It is not an option to not provide translations for Fedora.  I have not
omitted them.

>  I do not feel comfortable about this publishing tool, while at the
> same 
>  time, we had a good Proof of concept of Pintail at GUADEC. 
>  https://media.ccc.de/v/108-unconference-6
>  It may be just marketing, please tell me :) 
Did you look at my Proof of Concept?  What is making you feel
uncomfortable other than it not being pintail?

>  Will you convert from docbook to asciidoc every documentation from 
>  Fedora 7 ? I remember someone saying this conversion isn't easy. 
Please read my comments in the proposal about this.  I outline the
challenges, what has been discovered as ideas so far and you can see
some "quick-and-dirty" conversions in the proof of concept.

Also, I have recently attended a conference that has generated some
additional ideas for helping with this conversion.

>  At last, did you plan a mechanism to make comments for translator ?
>  Dummy example with C file : 
>  https://github.com/hughsie/appstream-glib/blob/master/client/as-builder.c... 
Can you please provide an example of this in the current Fedora
Documentation?

>  Anyway, to me, the most important is making 
>  update/publish/translate/publish processes easier and smoother.
>  The work you're doing is really needed and good. It can be this tool or 
>  another, but I just do not understand the move. Sorry for so big email! 
I understand where your concerns lie.  I strongly encourage you to read
through the whole proposal and I believe you will find most of your
concerns have been addressed and in many cases answered.  If you have
additional concerns or if you would like to schedule some time to talk
about this (in public so others can benefit), let me know.

I cannot make the standing docs meeting next week because of travel,
hence my desire to have this conversation via email.

Thank you.

regards,

bex

[Jean-Baptiste]

Le 21/09/2016 à 12:46, Brian Exelbierd a écrit :
>  That is covered in the Proof of Concept section.  In short, yes, you
> can
>  publish multiple languages today. 
Perfect ! I indeed missed the building part of
the POC.

>  One thing that I want to hear from the Translation Team is how they
> want
>  to handle untranslated and partially translated texts. 
My point of view is to do like we have for Website : periodic automatic 
publishing, even if incomplete (it's also what we do for most projects). 
I'll ask translators about this to have more than one voice.
>  I understand where your concerns lie. I strongly encourage you to
> read
>  through the whole proposal and I believe you will find most of your
>  concerns have been addressed and in many cases answered.  If you have
>  additional concerns or if you would like to schedule some time to talk
>  about this (in public so others can benefit), let me know.
>
>  I cannot make the standing docs meeting next week because of travel,
>  hence my desire to have this conversation via email.
>
>  Thank you.
>
>  regards,
>
>  bex
>  _______________________________________________ 
Thank you for full answer, I now
understand the move :)

-- 
Jean-Baptiste Holcroft

[Brian Exelbierd]

On Wed, Sep 21, 2016, at 07:36 PM, Jean-Baptiste Holcroft wrote:
>  Le 21/09/2016 à 12:46, Brian Exelbierd a écrit : 
>  > One thing that I want to hear from the Translation Team is how
> they want
>  > to handle untranslated and partially translated texts.
>  
>  My point of view is to do like we have for Website : periodic automatic 
>  publishing, even if incomplete (it's also what we do for most projects). 
>  I'll ask translators about this to have more than one voice. 
If I can ask, please focus on what we want to get to in the future and
then we can figure out the steps to get there.

For example, the answer from translation might be:

We would like to have immediate access to updated strings so please push
new strings as soon as they are cleared for publication in English.  We
would like to not have to notify you of updates to translations and
instead request that you just republish every language on a weekly
schedule.  We realize that you will inevitably publish incomplete
translations.  We also realize that you will publish when it is best for
you and may not publish all documents in all languages at one time.

>  Thank you for full answer, I now understand the move :) 
I am glad to hear it.

regards,

bex

[Shaun McCance]

On Wed, 2016-09-21 at 12:46 +0200, Brian Exelbierd wrote:
>  On Tue, Sep 20, 2016, at 08:50 PM, Jean-Baptiste Holcroft wrote:
>  > 
>  > Hi Brian,
>  > 
>  > I do not understand, isn't Gnome community is going to move from
>  > Mallard 
>  > to Pintail ?
>  Pintail is a site builder.  Mallard is a markup language.
>  
>  I know that pintail is being considered by Gnome for use as a site
>  builder.  I haven't seen the announcement about the adoption of
>  it.  I
>  don't believe it is feature complete yet.  I also don't track Gnome
>  so
>  if it was formally adopted as the path forward, I may have just not
>  seen
>  the announcement. 
For GNOME's needs, it is feature complete for user docs. It just needs
ops work, which probably won't happen until the next docs hackfest,
because there's no paid staff. You won't see any formal announcements,
short of it just happening. GNOME just doesn't work that way.

--
Shaun

[Zach Oglesby]

On Tue, Sep 20, 2016, at 03:47 AM, Brian Exelbierd wrote:
>  Hi All,
>
>  I am sorry I missed yesterday's meeting, I am at a conference
>  this week.
>
>  I have written a longish proposal
>  (http://www.winglemeyer.org/fedora_docs_proposal/latest/proposal/overview....)
>  about adopting an AsciiBinder toolchain.
>
>  I've tried to outline the challenges we have today and how I believe
>  this will get us a new documentation website and process
>  quickly.  There
>  is a Proof of Concept included with details on how you can
>  replicate my
>  work.
>
>  I'd like feedback and to discuss if we can move forward with this
>  proposal.  Can we please use email as travel will also prevent me from
>  attending next week's meeting. 
Sorry for posting this back to the top, lots of the replies are off
topic and I could not find a good spot to jump in.

My personal opinion on this is that while asciibinder is easier to setup
and get running, it puts us at the mercy of a few teams inside of Red
Hat again. While I may be misremembering the past, I recall Publican
being much more widely used than you seem to, but over time it lost
ground to other tools and the team working on it got smaller. The same
thing will happen if the teams working on asciibinder move on.

On the other hand, Shaun's career has been built on making tools for
documentation; he was hired by Red Hat becuase of this. While it is ture
that he is currently the only one working on pintail, he has a better
understanding of documention life cycle becuase of the length of time he
has been working in this domain. I do not see a diffrence between a team
of people working on Red Hat products commiting to a tool as better than
one person working on somthing that he is passionate about and has a
proven track record on. I would much rather be reliant on Shuan's work
than the whims of another team inside of Red Hat. I get that we are not
making a lot of progress moving to pintail, but it is my opinion that in
the long run it is the better tool.

[Brian Exelbierd]

>  On Thu, Sep 22, 2016, at 06:08 PM, Zach Oglesby wrote:
>  My personal opinion on this is that while asciibinder is easier to setup and get running,
> it puts us at the mercy of a few teams inside of Red Hat again. While I may be
> misremembering the past, I recall Publican being much more widely used than you seem to,
> but over time it lost ground to other tools and the team working on it got smaller. The
> same thing will happen if the teams working on asciibinder move on.  
I respect your opinion and I note that I came in at the end of publican's life, not
during it's heyday.

One thing that attracts me to AsciiBinder is that it is used by communities, albeit many
with strong RH contribution, and not just inside of RH.  In fact, AsciiBinder is not
currently used inside of RH at all, as far as I know.  I have also met at least one non-RH
group and non-RH dominant community that uses AsciiBinder.  This plus the relative
simplicity of the tool make me optimistic about its future.

I also believe that we are choosing tools for the next few years, not the next decade.  I
think that this space is changing a lot and that agility is more important than trying be
on the same toolchain over an extended period of time.  

Additionally, AsciiDoc seems to open up a world of tooling options to us and reduces our
risk of dependency on anyone, RH or Shaun.  Anecdotally, AsciiDoc also appears to recharge
contributing communities.

Therefore, even if we as a community decide to go with pintail, I think it is critical
that we both migrate to AsciiDoc as soon as possible and get something running by Fedora
26.  Ultimately our docs are only as good as our contributor count.  We must make all
efforts to get an easier contribution workflow in place immediately.

>  On the other hand, Shaun's career has been built on making tools
> for documentation; he was hired by Red Hat becuase of this. While it is ture that he is
> currently the only one working on pintail, he has a better understanding of documention
> life cycle becuase of the length of time he has been working in this domain. I do not see
> a diffrence between a team of people working on Red Hat products commiting to a tool as
> better than one person working on somthing that he is passionate about and has a proven
> track record on. I would much rather be reliant on Shuan's work than the whims of
> another team inside of Red Hat. I get that we are not making a lot of progress moving to
> pintail, but it is my opinion that in the long run it is the better tool.  
While Shaun's career may have been built on tooling, I don't believe he or anyone
else is omniscient.  I don't think Fedora is in a position to be the first or an early
adopter of this tooling.  AsciiBinder and other toolchains have had greater adoption so
far and therefore more people have hit and fixed the bugs.

Going back to my earlier comments, would it be worthwhile to "kick the ball down the
field" with AsciiBinder or another tool? We can always change to pintail if that is a
better choice down the road.

regards,

bex