Tooling, Tooling, Tooling

[Brian Exelbierd]

This email is to drive some discussion around $subject.  It follows from
a blog soon to be posted on the Fedora Community blog
(https://communityblog.fedoraproject.org).  The text below is copied
from that blog:

Tooling, Tooling, Tooling

There was strong consensus around changing to new tools and markups. In
fact, most of the tooling conversations were held in small groups near
the end of the meeting. There was a desire to continue to see a drive to
simpler contribution and publication.

The only significant question was around the community, upstream
adoption and contributor base for pintail which is the central tool in
the new processing flow. People were very concerned that there wasn't
evidence of enough adoption and contribution to prevent the project from
being at risk of going either unmaintained or slowly maintained.

Please reply here for discussion.

regards,

bex

[Tummala Dhanvi]

On Thu, Aug 11, 2016 at 7:04 PM, Brian Exelbierd <bex(a)pobox.com&gt; wrote:
>  This email is to drive some discussion around $subject.  It follows
> from
>  a blog soon to be posted on the Fedora Community blog
>  (https://communityblog.fedoraproject.org).  The text below is copied
>  from that blog:
>
>  Tooling, Tooling, Tooling
>
>  There was strong consensus around changing to new tools and markups. In
>  fact, most of the tooling conversations were held in small groups near
>  the end of the meeting. There was a desire to continue to see a drive to
>  simpler contribution and publication. 
I also agree with changing to newer tools which makes writing the docs
a lot simplier.

>  The only significant question was around the community, upstream
>  adoption and contributor base for pintail which is the central tool in
>  the new processing flow. People were very concerned that there wasn't
>  evidence of enough adoption and contribution to prevent the project from
>  being at risk of going either unmaintained or slowly maintained.
>  
First let me briefly explain how the new process works.

* Docs are written in AsciiDoc (https://en.wikipedia.org/wiki/AsciiDoc)
* Converted to Mallard (http://projectmallard.org/)
* Publish them using pintail (https://github.com/projectmallard/pintail)

Docs team had came to this conclusion after considering various
alternatives (https://communityblog.fedoraproject.org/event-report-fedora-docs-fad/,
https://communityblog.fedoraproject.org/event-report-fedora-docs-fad/)

AsciiDoc is widely used various projects (http://asciidoc.org/#X6)

Gnome is using Mallard for writing docs
(https://wiki.gnome.org/DocumentationProject/Contributing#Write_in_Mallard)

I agree to some extent that there is no enough evidence of adoption
and contribution (Shaun has written 99% of the tools!), but since
Gnome is adopting Mallard we should feel confident to some extent.

If by chance the Mallard goes unmaintained we could also switch to
other tools (like Asciidoctor http://asciidoctor.org/) for publishing
as we write the docs in Asciidoc format. But this method reduces the
features that we wanted to use.


PS:  Brian congrats for becoming Fedora's Community Co-ordinator.
-- 
Regards
Tummala Dhanvi

https://www.dhanvi.org
"Only thing that can never be 'RE-CYCLED' is 'WASTED TIME' ".

[Lailah]

Hello,

Sorry for the late reply and maybe I'm going to ask a silly question
but...  Is it Mallard a programme or a web based tool...? 
If I want to write something... where or how should I do it?  Is there
any specific programmes for it?



Cheers, and thanks
Sylvia



On Sun, 2016-09-04 at 17:31 +0530, Tummala Dhanvi wrote:
>  > > On Thu, Aug 11, 2016 at 7:04 PM, Brian Exelbierd
> <bex(a)pobox.com&gt; 
wrote:
>  > > > This email is to drive some discussion around
> $subject.  It follows 
from
>  > a blog soon to be posted on the Fedora Community blog
>  > > > > > (https://communityblog.fedoraproject.org).  The text below is
copied
>  > from that blog:
>  > 
>  > Tooling, Tooling, Tooling
>  > 
>  > > > There was strong consensus around changing to new tools and 
markups.
In
>  > > > fact, most of the tooling conversations were held in
> small groups 
near
>  > > > the end of the meeting. There was a desire to continue
> to see a 
drive to
>  > simpler contribution and publication.
>  
>  > I also agree with changing to newer tools which makes writing the 
docs
>  a lot simplier.
>  
>  > 
>  > The only significant question was around the community, upstream
>  > > > adoption and contributor base for pintail which is the central tool
in
>  > > > the new processing flow. People were very concerned
> that there 
wasn't
>  > > > evidence of enough adoption and contribution to
> prevent the project 
from
>  > being at risk of going either unmaintained or slowly
> maintained.
>  > 
>  
>  First let me briefly explain how the new process works.
>  
>  > * Docs are written in AsciiDoc (https://en.wikipedia.org/wiki/AsciiDo 
c)
>  > * Converted to Mallard (http://projectmallard.org/)
>  > * Publish them using pintail (https://github.com/projectmallard/pinta 
il)
>  
>  Docs team had came to this conclusion after considering various
>  > alternatives (https://communityblog.fedoraproject.org/event-report-fe
dora-docs-fad/,
>  >
> https://communityblog.fedoraproject.org/event-report-fedora-docs-fad/ 
)
>  
>  > AsciiDoc is widely used various projects (http://asciidoc.org/#X6)
>  
>  Gnome is using Mallard for writing docs
>  > (https://wiki.gnome.org/DocumentationProject/Contributing#Write_in_Ma 
llard)
>  
>  I agree to some extent that there is no enough evidence of adoption
>  and contribution (Shaun has written 99% of the tools!), but since
>  Gnome is adopting Mallard we should feel confident to some extent.
>  
>  If by chance the Mallard goes unmaintained we could also switch to
>  > other tools (like Asciidoctor http://asciidoctor.org/) for publishing
>  as we write the docs in Asciidoc format. But this method reduces the
>  features that we wanted to use.
>  
>  
>  PS:  Brian congrats for becoming Fedora's Community Co-ordinator.

[Simon Clark]

On 9 September 2016 at 08:34, Sylvia <bhkohane(a)gmail.com&gt; wrote:

>  Hello,
>
>  Sorry for the late reply and maybe I'm going to ask a silly question
>  but...  Is it Mallard a programme or a web based tool...?
>  If I want to write something... where or how should I do it?  Is there any
>  specific programmes for it?
>
>
>
>  Cheers, and thanks
>  Sylvia
>
>
>
>
>  On Sun, 2016-09-04 at 17:31 +0530, Tummala Dhanvi wrote:
>
>  On Thu, Aug 11, 2016 at 7:04 PM, Brian Exelbierd <bex(a)pobox.com&gt; wrote:
>
>
>  This email is to drive some discussion around $subject.  It follows from
>  a blog soon to be posted on the Fedora Community blog
>  (https://communityblog.fedoraproject.org).  The text below is copied
>  from that blog:
>
>  Tooling, Tooling, Tooling
>
>  There was strong consensus around changing to new tools and markups. In
>  fact, most of the tooling conversations were held in small groups near
>  the end of the meeting. There was a desire to continue to see a drive to
>  simpler contribution and publication.
>
>
>
>  I also agree with changing to newer tools which makes writing the docs
>  a lot simplier.
>
>
>
>
>  The only significant question was around the community, upstream
>  adoption and contributor base for pintail which is the central tool in
>  the new processing flow. People were very concerned that there wasn't
>  evidence of enough adoption and contribution to prevent the project from
>  being at risk of going either unmaintained or slowly maintained.
>
>
>
>
>  First let me briefly explain how the new process works.
>
>  * Docs are written in AsciiDoc (https://en.wikipedia.org/wiki/AsciiDoc)
>  * Converted to Mallard (http://projectmallard.org/)
>  * Publish them using pintail (https://github.com/projectmallard/pintail)
>
>  Docs team had came to this conclusion after considering various
>  alternatives
> (https://communityblog.fedoraproject.org/event-report-fedora-docs-fad/,htt...)
>
>  AsciiDoc is widely used various projects (http://asciidoc.org/#X6)
>
>  Gnome is using Mallard for writing docs
>  (https://wiki.gnome.org/DocumentationProject/Contributing#Write_in_Mallard)
>
>  I agree to some extent that there is no enough evidence of adoption
>  and contribution (Shaun has written 99% of the tools!), but since
>  Gnome is adopting Mallard we should feel confident to some extent.
>
>  If by chance the Mallard goes unmaintained we could also switch to
>  other tools (like Asciidoctor http://asciidoctor.org/) for publishing
>  as we write the docs in Asciidoc format. But this method reduces the
>  features that we wanted to use.
>
>
>  PS:  Brian congrats for becoming Fedora's Community Co-ordinator.
>
>
>  --
>  docs mailing list
>  docs(a)lists.fedoraproject.org
>  To unsubscribe:
>  https://lists.fedoraproject.org/admin/lists/[e-mail]
>  
Hi Sylvia,

Mallard is a markup language for writing topic-based documentation.  The
Ten Minute Tour at  http://projectmallard.org/about/learn/tenminutes shows
how it works.

Simon

[Lailah]

Oh!
Thanks.  Looks pretty nice. This is something that even me can do.

:-) 
Sylvia

On Fri, 2016-09-09 at 14:28 +0100, Simon Clark wrote:
>  
>  > On 9 September 2016 at 08:34, Sylvia <bhkohane(a)gmail.com&gt; wrote:
>  > Hello,
>  > 
>  > > > Sorry for the late reply and maybe I'm going to ask a silly
question but...  Is it Mallard a programme or a web based tool...? 
>  > > > If I want to write something... where or how should I
> do it?  Is 
there any specific programmes for it?
>  > 
>  > 
>  > 
>  > Cheers, and thanks
>  > Sylvia
>  > 
>  > 
>  > 
>  > 
>  > On Sun, 2016-09-04 at 17:31 +0530, Tummala Dhanvi wrote:
>  > > > > > > > > On Thu, Aug 11, 2016 at 7:04 PM, Brian Exelbierd
> <bex(a)pobox.com&gt; 
wrote:
>  > > > > > > > This email is to drive some
> discussion around $subject.  It 
follows from
>  > > > a blog soon to be posted on the Fedora Community blog
>  > > > > > > > > > > >
> (https://communityblog.fedoraproject.org).  The text below is 
copied
>  > > > from that blog:
>  > > > 
>  > > > Tooling, Tooling, Tooling
>  > > > 
>  > > > > > > > There was strong consensus around changing to new
> tools and 
markups. In
>  > > > > > > > fact, most of the tooling
> conversations were held in small 
groups near
>  > > > > > > > the end of the meeting. There was
> a desire to continue to see a 
drive to
>  > > > simpler contribution and publication.
>  > > 
>  > > > > > I also agree with changing to newer tools which makes writing
> the 
docs
>  > > a lot simplier.
>  > > 
>  > > > 
>  > > > > > > > The only significant question was around the
> community, 
upstream
>  > > > > > > > adoption and contributor base for
> pintail which is the central 
tool in
>  > > > > > > > the new processing flow. People
> were very concerned that there 
wasn't
>  > > > > > > > evidence of enough adoption and
> contribution to prevent the 
project from
>  > > > > > > > being at risk of going either
> unmaintained or slowly 
maintained.
>  > > > 
>  > > 
>  > > First let me briefly explain how the new process works.
>  > > 
>  > > > > > * Docs are written in AsciiDoc
> (https://en.wikipedia.org/wiki/Asc 
iiDoc)
>  > > > > > * Converted to Mallard
> (http://projectmallard.org/)
>  > > > > > * Publish them using pintail
> (https://github.com/projectmallard/p 
intail)
>  > > 
>  > > Docs team had came to this conclusion after considering various
>  > > > > > alternatives
> (https://communityblog.fedoraproject.org/event-repor 
t-fedora-docs-fad/,
>  > > > > >
> https://communityblog.fedoraproject.org/event-report-fedora-docs- 
fad/)
>  > > 
>  > > > > > AsciiDoc is widely used various projects
> (http://asciidoc.org/#X6 
)
>  > > 
>  > > Gnome is using Mallard for writing docs
>  > > > > >
> (https://wiki.gnome.org/DocumentationProject/Contributing#Write_i 
n_Mallard)
>  > > 
>  > > > > > I agree to some extent that there is no enough evidence of
adoption
>  > > and contribution (Shaun has written 99% of the tools!), but
> since
>  > > > > > Gnome is adopting Mallard we should feel confident to some
extent.
>  > > 
>  > > > > > If by chance the Mallard goes unmaintained we could also switch
to
>  > > > > > > > > other tools (like Asciidoctor
> http://asciidoctor.org/) for 
publishing
>  > > > > > as we write the docs in Asciidoc format. But
> this method reduces 
the
>  > > features that we wanted to use.
>  > > 
>  > > 
>  > > PS:  Brian congrats for becoming Fedora's Community Co-ordinator.
>  > 
>  > 
>  > 
>  > --
>  > 
>  > docs mailing list
>  > 
>  > docs(a)lists.fedoraproject.org
>  > 
>  > To unsubscribe:
>  > 
>  > > > https://lists.fedoraproject.org/admin/lists/[e-mail]
t.org
>  
>  Hi Sylvia,
>  
>  > > Mallard is a markup language for writing topic-based documentation.  
The
Ten Minute Tour at  http://projectmallard.org/about/learn/tenminu
tes shows how it works.
>  
>  Simon 
>  
>  
>  --
>  docs mailing list
>  docs(a)lists.fedoraproject.org
>  To unsubscribe:
>  > https://lists.fedoraproject.org/admin/lists/[e-mail]. 
org

[Brian Exelbierd]

On Sun, Sep 4, 2016, at 02:01 PM, Tummala Dhanvi wrote:
>  If by chance the Mallard goes unmaintained we could also switch to
>  other tools (like Asciidoctor http://asciidoctor.org/) for publishing
>  as we write the docs in Asciidoc format. But this method reduces the
>  features that we wanted to use. 
What are the specific features of pintail (or the pipeline of converting
AsciiDoc to Mallard) that we want to use that aren't available in other
solutions?

regards,

bex

PS: Sorry for the late reply

[Shaun McCance]

On Sun, 2016-09-18 at 15:44 +0200, Brian Exelbierd wrote:
>  On Sun, Sep 4, 2016, at 02:01 PM, Tummala Dhanvi wrote:
>  > 
>  > If by chance the Mallard goes unmaintained we could also switch to
>  > other tools (like Asciidoctor http://asciidoctor.org/) for
>  > publishing
>  > as we write the docs in Asciidoc format. But this method reduces
>  > the
>  > features that we wanted to use. 
The chances of any of this going unmaintained are pretty small. We're
talking about a tool set that's been continually supported for over 15
years, and which has the backing of one of the oldest and most mature
projects in all of open source.

>  What are the specific features of pintail (or the pipeline of
>  converting
>  AsciiDoc to Mallard) that we want to use that aren't available in
>  other
>  solutions? 
I can only speak to the solutions we evaluated at the FAD, and Pete or
Zach might have have different thoughts. But here's what I think were
some compelling bits:

* Ability to manage entire site structure.
* Ability to grab different documents from different git repositories.
* Ability to work with existing content, without requiring everything
to be converted at once.
* Per-document search that works. Most site tools aren't designed for
docs and just have global search.
* Well-managed translations with access to powerful translation tools.

--
Shaun

[Brian Exelbierd]

On Mon, Sep 19, 2016, at 06:10 PM, Shaun McCance wrote:
>  On Sun, 2016-09-18 at 15:44 +0200, Brian Exelbierd wrote:
>  > What are the specific features of pintail (or the pipeline of
>  > converting
>  > AsciiDoc to Mallard) that we want to use that aren't available in
>  > other
>  > solutions?
>  
>  I can only speak to the solutions we evaluated at the FAD, and Pete or
>  Zach might have have different thoughts. But here's what I think were
>  some compelling bits:
>  
>  * Ability to manage entire site structure.
>  * Ability to grab different documents from different git repositories. 
These are available in other tools and are also demonstrated in my POC.

>  * Ability to work with existing content, without requiring
> everything
>  to be converted at once. 
This is a deliberate position I am taking in my POC.

>  * Per-document search that works. Most site tools aren't designed
> for
>  docs and just have global search. 
I believe this is a solveable problem.  It is on my list to do a POC of
as soon as I can.

Today the Fedora Docs site doesn't feature search.  I believe a solution
that can move us ahead should not be penalized if it doesn't provide
search.  Search has not, as far as I know, been identified as a core
problem with our site that is inhibiting contribution.

>  * Well-managed translations with access to powerful translation
> tools. 
I presume you mean Zanata.  My POC and other tools can use Zanata.

regards,

bex

[Matthew Miller]

On Wed, Sep 21, 2016 at 12:50:52PM +0200, Brian Exelbierd wrote:
>  > * Per-document search that works. Most site tools aren't
> designed for
>  > docs and just have global search.
>  I believe this is a solveable problem.  It is on my list to do a POC of
>  as soon as I can. 
Isn't this just "ctrl-f" in my web browser?

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

[Brian Exelbierd]

On Wed, Sep 21, 2016, at 04:30 PM, Matthew Miller wrote:
>  On Wed, Sep 21, 2016 at 12:50:52PM +0200, Brian Exelbierd wrote:
>  > > * Per-document search that works. Most site tools aren't designed for
>  > > docs and just have global search.
>  > I believe this is a solveable problem.  It is on my list to do a POC of
>  > as soon as I can.
>  
>  Isn't this just "ctrl-f" in my web browser? 
No as our output is chunked.  This only works if you have html-single
style output.  If you get to the right section, it works well :)

regards,

bex

[Matthew Miller]

On Wed, Sep 21, 2016 at 05:41:54PM +0200, Brian Exelbierd wrote:
>  > Isn't this just "ctrl-f" in my web browser?
>  No as our output is chunked.  This only works if you have html-single
>  style output.  If you get to the right section, it works well :) 
Serious question: is our output chunked for any useful reason? I
understand why sites which get advertising revenue and want to inflate
page views do it, but why would we?


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

[Zach Oglesby]

On Wed, Sep 21, 2016, at 12:45 PM, Matthew Miller wrote:
>  On Wed, Sep 21, 2016 at 05:41:54PM +0200, Brian Exelbierd wrote:
>  > > Isn't this just "ctrl-f" in my web browser?
>  > No as our output is chunked.  This only works if you have html-
>  > single
>  > style output.  If you get to the right section, it works well :)
>
>  Serious question: is our output chunked for any useful reason? I
>  understand why sites which get advertising revenue and want to inflate
>  page views do it, but why would we? 
A giant wall of text is not readable, and can be overwhelming. Look at
the install guide or sys admin guide in html single page.

https://docs.fedoraproject.org/en-US/Fedora/24/html-single/Installation_G...
https://docs.fedoraproject.org/en-US/Fedora/24/html-single/System_Adminis...

[Ben Cotton]

On Wed, Sep 21, 2016 at 12:48 PM, Zach Oglesby <zach(a)oglesby.co&gt; wrote:
>  A giant wall of text is not readable, and can be overwhelming.
It's also easier to link directly to the relevant content if it's
broken up appropriately. There's definitely a too-small-chunk problem
to avoid, but on the whole, a page per section or so is a good
balance.


-- 
Ben Cotton

[Matthew Miller]

On Wed, Sep 21, 2016 at 12:57:40PM -0400, Ben Cotton wrote:
>  > A giant wall of text is not readable, and can be overwhelming.
>  It's also easier to link directly to the relevant content if it's
>  broken up appropriately. There's definitely a too-small-chunk problem
>  to avoid, but on the whole, a page per section or so is a good
>  balance. 
I definitely appreciate anchor tags, with easy ways to get the link,
and maybe javascript to change the #hash in the URL as I scroll to a
new section.

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

[Brian Exelbierd]

On Wed, Sep 21, 2016, at 07:12 PM, Matthew Miller wrote:
>  On Wed, Sep 21, 2016 at 12:57:40PM -0400, Ben Cotton wrote:
>  > > A giant wall of text is not readable, and can be overwhelming.
>  > It's also easier to link directly to the relevant content if it's
>  > broken up appropriately. There's definitely a too-small-chunk problem
>  > to avoid, but on the whole, a page per section or so is a good
>  > balance.
>  
>  I definitely appreciate anchor tags, with easy ways to get the link,
>  and maybe javascript to change the #hash in the URL as I scroll to a
>  new section. 

I haven't seen this in action before.  Have an example?  It sounds
interesting.

regards,

bex

[Matthew Miller]

On Wed, Sep 21, 2016 at 12:48:37PM -0400, Zach Oglesby wrote:
>  A giant wall of text is not readable, and can be overwhelming. Look
> at
>  the install guide or sys admin guide in html single page.
>  
>  https://docs.fedoraproject.org/en-US/Fedora/24/html-single/Installation_G...
>
> https://docs.fedoraproject.org/en-US/Fedora/24/html-single/System_Adminis...
But the sysadmin guide isn't *really* a single document. Each of its
chapters could easily be stand-alone. Maybe they could be linked by a
"sysadmin" tag.

I guess I can see the Installation Guide as a single book-like thing,
but it feels like a special case.


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

[Brian Exelbierd]

On Wed, Sep 21, 2016, at 07:11 PM, Matthew Miller wrote:
>  On Wed, Sep 21, 2016 at 12:48:37PM -0400, Zach Oglesby wrote:
>  > A giant wall of text is not readable, and can be overwhelming. Look at
>  > the install guide or sys admin guide in html single page.
>  > 
>  >
> https://docs.fedoraproject.org/en-US/Fedora/24/html-single/Installation_G...
>  >
> https://docs.fedoraproject.org/en-US/Fedora/24/html-single/System_Adminis...
>  
>  But the sysadmin guide isn't *really* a single document. Each of its
>  chapters could easily be stand-alone. Maybe they could be linked by a
>  "sysadmin" tag. 
This gets right at the heart of the desire to move away from books and
to topic based writing.

>  I guess I can see the Installation Guide as a single book-like
> thing,
>  but it feels like a special case. 
agreed.

regards,

bex

[Shaun McCance]

On Wed, 2016-09-21 at 12:50 +0200, Brian Exelbierd wrote:
>  On Mon, Sep 19, 2016, at 06:10 PM, Shaun McCance wrote:
>  > * Well-managed translations with access to powerful translation
>  > tools.
>  I presume you mean Zanata.  My POC and other tools can use Zanata. 
Actually, I meant that by going through an XML layer, it has access to
itstool (though it can use other tools instead).

--
Shaun