[Qemu-devel] Qemu-devel] Poll on QEMU documentation project

[Qemu-devel] Qemu-devel] Poll on QEMU documentation project

[G 3]

On Jan 26, 2017, at 12:00 PM, qemu-devel-request@nongnu.org wrote:

>
> Hi all,
>
> as you may know I've been collecting some ideas about documentation  
> for
> QEMU at http://wiki.qemu-project.org/Features/Documentation.
>
> I've now prepared a poll to understand how familiars developers are  
> with
> various documentation tools.  I've CCed people with most commits to  
> QEMU
> documentation, or with whom I have discussed about this before, but
> everybody's opinion is of course welcome!
>
> The poll is hosted with Google Forms and you can fill it in at
> https://goo.gl/Yfxj1M.  If you hate Google Forms, contact me  
> offlist and
> I'll send you the questions by email (and remind you when I need  
> someone
> to review my patches).
>
> Paolo
>
>
> tl;dr: poll is at https://goo.gl/Yfxj1M


For this question:
What's your opinion on the maintainability of the following  
documentation formats?

Is it from 1(least maintainable) to 5 (most maintainable)?

The survey looks good. I will take it.

Re: [Qemu-devel] Qemu-devel] Poll on QEMU documentation project

[Paolo Bonzini]

On 26/01/2017 18:28, G 3 wrote:
> 
> On Jan 26, 2017, at 12:00 PM, qemu-devel-request@nongnu.org wrote:
> 
>>
>> Hi all,
>>
>> as you may know I've been collecting some ideas about documentation for
>> QEMU at http://wiki.qemu-project.org/Features/Documentation.
>>
>> I've now prepared a poll to understand how familiars developers are with
>> various documentation tools.  I've CCed people with most commits to QEMU
>> documentation, or with whom I have discussed about this before, but
>> everybody's opinion is of course welcome!
>>
>> The poll is hosted with Google Forms and you can fill it in at
>> https://goo.gl/Yfxj1M.  If you hate Google Forms, contact me offlist and
>> I'll send you the questions by email (and remind you when I need someone
>> to review my patches).
>>
>> Paolo
>>
>>
>> tl;dr: poll is at https://goo.gl/Yfxj1M
> 
> 
> For this question:
> What's your opinion on the maintainability of the following
> documentation formats?
> 
> Is it from 1(least maintainable) to 5 (most maintainable)?
> 
> The survey looks good. I will take it.

Yes, all of them are 1=bad 5=good.

Paolo

Re: [Qemu-devel] Qemu-devel] Poll on QEMU documentation project

[G 3]

On Jan 26, 2017, at 12:30 PM, Paolo Bonzini wrote:

>
>
> On 26/01/2017 18:28, G 3 wrote:
>>
>> On Jan 26, 2017, at 12:00 PM, qemu-devel-request@nongnu.org wrote:
>>
>>>
>>> Hi all,
>>>
>>> as you may know I've been collecting some ideas about  
>>> documentation for
>>> QEMU at http://wiki.qemu-project.org/Features/Documentation.
>>>
>>> I've now prepared a poll to understand how familiars developers  
>>> are with
>>> various documentation tools.  I've CCed people with most commits  
>>> to QEMU
>>> documentation, or with whom I have discussed about this before, but
>>> everybody's opinion is of course welcome!
>>>
>>> The poll is hosted with Google Forms and you can fill it in at
>>> https://goo.gl/Yfxj1M.  If you hate Google Forms, contact me  
>>> offlist and
>>> I'll send you the questions by email (and remind you when I need  
>>> someone
>>> to review my patches).
>>>
>>> Paolo
>>>
>>>
>>> tl;dr: poll is at https://goo.gl/Yfxj1M
>>
>>
>> For this question:
>> What's your opinion on the maintainability of the following
>> documentation formats?
>>
>> Is it from 1(least maintainable) to 5 (most maintainable)?
>>
>> The survey looks good. I will take it.
>
> Yes, all of them are 1=bad 5=good.
>
> Paolo

Could we add HTML to the list of documentation formats?

Re: [Qemu-devel] Qemu-devel] Poll on QEMU documentation project

[Paolo Bonzini]

On 26/01/2017 18:40, G 3 wrote:
> 
> On Jan 26, 2017, at 12:30 PM, Paolo Bonzini wrote:
> 
>>
>>
>> On 26/01/2017 18:28, G 3 wrote:
>>>
>>> On Jan 26, 2017, at 12:00 PM, qemu-devel-request@nongnu.org wrote:
>>>
>>>>
>>>> Hi all,
>>>>
>>>> as you may know I've been collecting some ideas about documentation for
>>>> QEMU at http://wiki.qemu-project.org/Features/Documentation.
>>>>
>>>> I've now prepared a poll to understand how familiars developers are
>>>> with
>>>> various documentation tools.  I've CCed people with most commits to
>>>> QEMU
>>>> documentation, or with whom I have discussed about this before, but
>>>> everybody's opinion is of course welcome!
>>>>
>>>> The poll is hosted with Google Forms and you can fill it in at
>>>> https://goo.gl/Yfxj1M.  If you hate Google Forms, contact me offlist
>>>> and
>>>> I'll send you the questions by email (and remind you when I need
>>>> someone
>>>> to review my patches).
>>>>
>>>> Paolo
>>>>
>>>>
>>>> tl;dr: poll is at https://goo.gl/Yfxj1M
>>>
>>>
>>> For this question:
>>> What's your opinion on the maintainability of the following
>>> documentation formats?
>>>
>>> Is it from 1(least maintainable) to 5 (most maintainable)?
>>>
>>> The survey looks good. I will take it.
>>
>> Yes, all of them are 1=bad 5=good.
> 
> Could we add HTML to the list of documentation formats?

Since you have mentioned that in the comments and someone else mentioned
AsciiDoc, they weren't included because:

- HTML is mostly a destination format.  With the listed formats it is
possible to produce a variety of outputs (mostly HTML itself and PDF;
secondarily text or ePub or others).

- AsciiDoc was considered by the Linux kernel folks but they complained
about the tools.

Paolo

Re: [Qemu-devel] Qemu-devel] Poll on QEMU documentation project

[Peter Maydell]

On 26 January 2017 at 17:52, Paolo Bonzini <pbonzini@redhat.com> wrote:
> - HTML is mostly a destination format.  With the listed formats it is
> possible to produce a variety of outputs (mostly HTML itself and PDF;
> secondarily text or ePub or others).

It's an interesting question to ask what destination formats
we should be generating, though. At the moment we output
HTML, plain text, PDF and info. Personally I think that list
is too long and we should probably cut it down to HTML
and PDF or perhaps even just HTML.

thanks
-- PMM

Re: [Qemu-devel] Qemu-devel] Poll on QEMU documentation project

[Cornelia Huck]

On Thu, 26 Jan 2017 18:30:46 +0100
Paolo Bonzini <pbonzini@redhat.com> wrote:

> On 26/01/2017 18:28, G 3 wrote:
> > 
> > On Jan 26, 2017, at 12:00 PM, qemu-devel-request@nongnu.org wrote:
> > 
> >>
> >> Hi all,
> >>
> >> as you may know I've been collecting some ideas about documentation for
> >> QEMU at http://wiki.qemu-project.org/Features/Documentation.
> >>
> >> I've now prepared a poll to understand how familiars developers are with
> >> various documentation tools.  I've CCed people with most commits to QEMU
> >> documentation, or with whom I have discussed about this before, but
> >> everybody's opinion is of course welcome!
> >>
> >> The poll is hosted with Google Forms and you can fill it in at
> >> https://goo.gl/Yfxj1M.  If you hate Google Forms, contact me offlist and
> >> I'll send you the questions by email (and remind you when I need someone
> >> to review my patches).
> >>
> >> Paolo
> >>
> >>
> >> tl;dr: poll is at https://goo.gl/Yfxj1M
> > 
> > 
> > For this question:
> > What's your opinion on the maintainability of the following
> > documentation formats?
> > 
> > Is it from 1(least maintainable) to 5 (most maintainable)?
> > 
> > The survey looks good. I will take it.
> 
> Yes, all of them are 1=bad 5=good.

Ugh, so I had my answers the wrong way round :( Most of the surveys I
did recently had the order the other way round...

I'll send another form.

Re: [Qemu-devel] Qemu-devel] Poll on QEMU documentation project

[Markus Armbruster]

Peter Maydell <peter.maydell@linaro.org> writes:

> On 26 January 2017 at 17:52, Paolo Bonzini <pbonzini@redhat.com> wrote:
>> - HTML is mostly a destination format.  With the listed formats it is
>> possible to produce a variety of outputs (mostly HTML itself and PDF;
>> secondarily text or ePub or others).
>
> It's an interesting question to ask what destination formats
> we should be generating, though. At the moment we output
> HTML, plain text, PDF and info. Personally I think that list
> is too long and we should probably cut it down to HTML
> and PDF or perhaps even just HTML.

"What can we cut" is the wrong question.  The right one is "what are our
requirements".  Here's my try:

HTML: required
nroff with an macros: required
PDF: wanted (try printing a website)
plain text: nice to have (for me personally, more than that)
info: nice to have

If a solution we like can't provide something that's nice to have, we
can decide to take it anyway.

If a solution we like can provide something that's nice to have, we
should let it provide, unless it turns out to be a drag.

Re: [Qemu-devel] Qemu-devel] Poll on QEMU documentation project

[Peter Maydell]

On 27 January 2017 at 06:51, Markus Armbruster <armbru@redhat.com> wrote:
> "What can we cut" is the wrong question.  The right one is "what are our
> requirements".  Here's my try:
>
> HTML: required
> nroff with an macros: required
> PDF: wanted (try printing a website)
> plain text: nice to have (for me personally, more than that)
> info: nice to have
>
> If a solution we like can't provide something that's nice to have, we
> can decide to take it anyway.
>
> If a solution we like can provide something that's nice to have, we
> should let it provide, unless it turns out to be a drag.

Well, every extra documentation format:
 * increases the build time
 * increases the chances of makefile bugs
 * may require extra tooling to produce
 * either requires us to check it for problems or increases
   the chance of confusing users because that output format
   has a formatting problem that doesn't happen in the doc
   formats most people use
 * may require significant extra work to produce something
   that's actually useful: a manpage and an info doc aren't
   just the same content in a different file format, they
   should have definitely different contents and structure
   to fit what people expect a manpage or an info doc to be

So my list is:
 * HTML: required
 * PDF: nice-to-have

thanks
-- PMM

Re: [Qemu-devel] Qemu-devel] Poll on QEMU documentation project

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 1540 bytes --]

On Fri, Jan 27, 2017 at 10:08:49AM +0000, Peter Maydell wrote:
> On 27 January 2017 at 06:51, Markus Armbruster <armbru@redhat.com> wrote:
> > "What can we cut" is the wrong question.  The right one is "what are our
> > requirements".  Here's my try:
> >
> > HTML: required
> > nroff with an macros: required
> > PDF: wanted (try printing a website)
> > plain text: nice to have (for me personally, more than that)
> > info: nice to have
> >
> > If a solution we like can't provide something that's nice to have, we
> > can decide to take it anyway.
> >
> > If a solution we like can provide something that's nice to have, we
> > should let it provide, unless it turns out to be a drag.
> 
> Well, every extra documentation format:
>  * increases the build time
>  * increases the chances of makefile bugs
>  * may require extra tooling to produce
>  * either requires us to check it for problems or increases
>    the chance of confusing users because that output format
>    has a formatting problem that doesn't happen in the doc
>    formats most people use
>  * may require significant extra work to produce something
>    that's actually useful: a manpage and an info doc aren't
>    just the same content in a different file format, they
>    should have definitely different contents and structure
>    to fit what people expect a manpage or an info doc to be
> 
> So my list is:
>  * HTML: required
>  * PDF: nice-to-have

We also need to produce man pages for the command-line tools.

Stefan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 455 bytes --]

Re: [Qemu-devel] Qemu-devel] Poll on QEMU documentation project

[Markus Armbruster]

Stefan Hajnoczi <stefanha@gmail.com> writes:

> On Fri, Jan 27, 2017 at 10:08:49AM +0000, Peter Maydell wrote:
>> On 27 January 2017 at 06:51, Markus Armbruster <armbru@redhat.com> wrote:
>> > "What can we cut" is the wrong question.  The right one is "what are our
>> > requirements".  Here's my try:
>> >
>> > HTML: required
>> > nroff with an macros: required
>> > PDF: wanted (try printing a website)
>> > plain text: nice to have (for me personally, more than that)
>> > info: nice to have
>> >
>> > If a solution we like can't provide something that's nice to have, we
>> > can decide to take it anyway.
>> >
>> > If a solution we like can provide something that's nice to have, we
>> > should let it provide, unless it turns out to be a drag.
>> 
>> Well, every extra documentation format:
>>  * increases the build time

Yes.  The increase can range from "lost in the noise" through "painful"
to "prohibitive".  The more pain, the more gain we need to show to
justify.

Right now, documentation formatting is a drop in the compilation time
bucket.

>>  * increases the chances of makefile bugs

Yes.  Those can be a pain to debug, such as when you don't realize it's
a Makefile bug (instead of say a long-obsolete version of a tool playing
tricks on you on a platform you can't access).

Fortunately, such bugs get created mostly when we're messing with the
doc toolchain, which should be rare.

Right now, documentation formatting is a drop in the Makefile complexity
bucket.

>>  * may require extra tooling to produce

Again, the more pain, the more gain we need to show.

Right now, our build requirements for documentation are a drop in the
build requirements bucket on Linux.  Can't judge other hosts.

>>  * either requires us to check it for problems or increases
>>    the chance of confusing users because that output format
>>    has a formatting problem that doesn't happen in the doc
>>    formats most people use

Yes, formatting issues specific to the output format are possible.
Probably more likely when producing it involves options or tools that
aren't in common use.

>>  * may require significant extra work to produce something
>>    that's actually useful: a manpage and an info doc aren't
>>    just the same content in a different file format, they
>>    should have definitely different contents and structure
>>    to fit what people expect a manpage or an info doc to be

Yes, but isn't that a solved problem for us?

Any proposal that "unsolves" it needs to justify the pain by showing
commensurate gain.

>> So my list is:
>>  * HTML: required
>>  * PDF: nice-to-have
>
> We also need to produce man pages for the command-line tools.

That's what I meant by "nroff with an macros".  Hard requirement.

Re: [Qemu-devel] Qemu-devel] Poll on QEMU documentation project

[G 3]

I was thinking maybe we should add Rich Text Format, or maybe even a  
word processing format like OpenOffice, or Microsoft Word to the list  
of possible formats. These formats are super easy to use. No  
formatting rules to have to learn. All the user needs to do is just  
type up their contribute to the documentation in a word processor.  
The word processor would do all the formatting work. Tables, links,  
stylized text are all possible. This would allow us to export to  
other formats like HTML, PDF, and ascii text.

Re: [Qemu-devel] Qemu-devel] Poll on QEMU documentation project

[Paolo Bonzini]

On 01/02/2017 14:50, G 3 wrote:
> I was thinking maybe we should add Rich Text Format, or maybe even a
> word processing format like OpenOffice, or Microsoft Word to the list of
> possible formats. These formats are super easy to use. No formatting
> rules to have to learn. All the user needs to do is just type up their
> contribute to the documentation in a word processor. The word processor
> would do all the formatting work. Tables, links, stylized text are all
> possible. This would allow us to export to other formats like HTML, PDF,
> and ascii text.

That's exactly what we _don't_ want.

We need documentation to be consistent.  RTF, OpenOffice, etc. are
presentation-based format (or at least 99% users use them as such), and
this automatically disqualifies them.  We don't want our documentation
to be a mixture of Arial, Times New Roman and Comic Sans depending on
the user that's contributing.  Besides, conversion of word processor
documents to HTML usually looks terrible.

The requirements for the format are:

* support for HTML and man as output formats, optionally PDF and text
* support for QEMU's usual submission workflow
* producing documentation with a consistent look
* tool support and extensibility
* being easy to use and not too obscure

in this order.  Based on this, the only formats we could plausibly use
are Texinfo (if only because that's what we use now), Markdown,
restructuredText, Docbook and Asciidoc.  The poll mentioned all of these
except Asciidoc, plus LaTeX as a "control group".

Paolo

Re: [Qemu-devel] Qemu-devel] Poll on QEMU documentation project

[G 3]

On Feb 1, 2017, at 6:17 PM, Paolo Bonzini wrote:

>
>
> On 01/02/2017 14:50, G 3 wrote:
>> I was thinking maybe we should add Rich Text Format, or maybe even a
>> word processing format like OpenOffice, or Microsoft Word to the  
>> list of
>> possible formats. These formats are super easy to use. No formatting
>> rules to have to learn. All the user needs to do is just type up  
>> their
>> contribute to the documentation in a word processor. The word  
>> processor
>> would do all the formatting work. Tables, links, stylized text are  
>> all
>> possible. This would allow us to export to other formats like  
>> HTML, PDF,
>> and ascii text.
>
> That's exactly what we _don't_ want.
>
> We need documentation to be consistent.  RTF, OpenOffice, etc. are
> presentation-based format (or at least 99% users use them as such),  
> and
> this automatically disqualifies them.  We don't want our documentation
> to be a mixture of Arial, Times New Roman and Comic Sans depending on
> the user that's contributing.  Besides, conversion of word processor
> documents to HTML usually looks terrible.
>
> The requirements for the format are:
>
> * support for HTML and man as output formats, optionally PDF and text
> * support for QEMU's usual submission workflow
> * producing documentation with a consistent look
> * tool support and extensibility
> * being easy to use and not too obscure
>
> in this order.  Based on this, the only formats we could plausibly use
> are Texinfo (if only because that's what we use now), Markdown,
> restructuredText, Docbook and Asciidoc.  The poll mentioned all of  
> these
> except Asciidoc, plus LaTeX as a "control group".
>
> Paolo

Ok. I understand.

For the above requirements of "tool support and extensibility", what  
do you mean by this? Do you mean command-line tool support? What do  
you mean by extensibility?

Re: [Qemu-devel] Qemu-devel] Poll on QEMU documentation project

[Paolo Bonzini]

On 01/02/2017 15:36, G 3 wrote:
> On Feb 1, 2017, at 6:17 PM, Paolo Bonzini wrote:
>> The requirements for the format are:
>>
>> * support for HTML and man as output formats, optionally PDF and text
>> * support for QEMU's usual submission workflow
>> * producing documentation with a consistent look
>> * tool support and extensibility
>> * being easy to use and not too obscure
>>
>> in this order.  Based on this, the only formats we could plausibly use
>> are Texinfo (if only because that's what we use now), Markdown,
>> restructuredText, Docbook and Asciidoc.  The poll mentioned all of these
>> except Asciidoc, plus LaTeX as a "control group".
> 
> Ok. I understand.
> 
> For the above requirements of "tool support and extensibility", what do
> you mean by this? Do you mean command-line tool support? What do you
> mean by extensibility?

Basically, easily integrating QEMU-specific code in the build.  This
way, we don't need 20 different steps in the Makefile; instead a single
tool invocation will do everything from parsing the input, to extracting
documentation comments from C source, to finally generating the output.

Of course you need to find the right balance between redoing the same
work over and over (a solution purely based on Make can do that best)
and ease of use.

Paolo