On Sat, Nov 27, 2010 at 1:50 PM, Mike Frysinger <vapier@gentoo.org> wrote:
> On Saturday, November 27, 2010 16:39:04 Alec Warner wrote:
>> On Sat, Nov 27, 2010 at 6:53 AM, Zac Medico wrote:
>> > As it is, I'm fairly comfortable with docbook. Now you want me to learn
>> > a new format, with possible drawbacks, in order to try and draw in some
>> > contributions that may never happen?
>>
>> Here is where I would look for data. *Are there pending contributions?
>> *I have not seen anyone on this list specifically say "I'd write some
>> documentation if it was not in docbook." *I have had issues (years
>> ago) getting vapier to write documentation; but I assumed that was
>> because he hated writing docs and he contributed documentation after a
>> while.
>
> not sure where you're going with this, but i'm the one who started the doc/
> dir and introduced the docbook system. *obviously i have no problem with it
> and would rather see real examples of people who are being impeded by it
> rather than yet another "omg we need to switch to this awesome new format
> because it is so awesome".
> -mike
>

I'm saying you should write more docs! But we agree on the other point

On Sat, Nov 27, 2010 at 10:50 PM, Mike Frysinger <vapier@gentoo.org> wrote:
> On Saturday, November 27, 2010 16:39:04 Alec Warner wrote:
>> On Sat, Nov 27, 2010 at 6:53 AM, Zac Medico wrote:
>> > As it is, I'm fairly comfortable with docbook. Now you want me to learn
>> > a new format, with possible drawbacks, in order to try and draw in some
>> > contributions that may never happen?
>>
>> Here is where I would look for data. *Are there pending contributions?
>> *I have not seen anyone on this list specifically say "I'd write some
>> documentation if it was not in docbook." *I have had issues (years
>> ago) getting vapier to write documentation; but I assumed that was
>> because he hated writing docs and he contributed documentation after a
>> while.
>
> not sure where you're going with this, but i'm the one who started the doc/
> dir and introduced the docbook system. *obviously i have no problem with it
> and would rather see real examples of people who are being impeded by it
> rather than yet another "omg we need to switch to this awesome new format
> because it is so awesome".
> -mike
>

Hi Mike,

at the beginning, I've just made a try and see if it would be
feasible, then I decided to suggest the portage team about it, that's
all.
As I said before, if the majority of relevant people are not
interested and want to stay with a docbook source, that's totally
fine. I never meant to change habits neither do I pretend that
asciidoc is awesome. It was simply a suggestion, in case you did not
know it.

I also understand that it's not good to change formats all the time.If
docbook is well established as the reference tool for you to make
docs, then please, keep the docbook format and just forget about the
discussion.

As an aside note, that would be a bit more pleasant to read if the
current doc had a bit of css styling. Would you be against that ? I am
not a designer at all, but I can still suggest a css for docbook,
unless some Gentoo project already suggests one.

Best regards,
Lionel

On Sat, 27 Nov 2010, Zac Medico wrote:

> On 11/27/2010 01:25 AM, Sebastian Pipping wrote:
> > In case DocBook is keeping contributions down than cutting away certain
> > flexibility to increase contributions could be a good trade-off, too.
>
> I'm not sure that docbook represents a significant barrier in this
> respect. It's hard to speculate. Maybe if we had a survey sampling the
> opinions of a broad spectrum of open-source developers, then we'd have
> more to go on.

My impression from git development is that, with asciidoc, we got a lot of
documentation patches from users who read the documentation, found that it
was inaccurate or unclear, and were able to propose corrections based on
their observation of the actual behavior. I believe we also got
documentation of previously undocumented functionality, written by people
who had found out how to use it from some other source after failing to
find it mentioned in the documentation. I suspect that docbook is too high
a barrier for some people when asciidoc wouldn't be; the question is
really whether any of these people are the audience for portage
documentation.

-Daniel
*This .sig left intentionally blank*

On Monday, November 29, 2010 18:59:04 Daniel Barkalow wrote:
> On Sat, 27 Nov 2010, Zac Medico wrote:
> > On 11/27/2010 01:25 AM, Sebastian Pipping wrote:
> > > In case DocBook is keeping contributions down than cutting away certain
> > > flexibility to increase contributions could be a good trade-off, too.
> >
> > I'm not sure that docbook represents a significant barrier in this
> > respect. It's hard to speculate. Maybe if we had a survey sampling the
> > opinions of a broad spectrum of open-source developers, then we'd have
> > more to go on.
>
> My impression from git development is that, with asciidoc, we got a lot of
> documentation patches from users who read the documentation, found that it
> was inaccurate or unclear, and were able to propose corrections based on
> their observation of the actual behavior. I believe we also got
> documentation of previously undocumented functionality, written by people
> who had found out how to use it from some other source after failing to
> find it mentioned in the documentation. I suspect that docbook is too high
> a barrier for some people when asciidoc wouldn't be; the question is
> really whether any of these people are the audience for portage
> documentation.

all of the user-facing documentation is in the man pages. all of the docbook
pages are generally more internal stuff. so any of the corrections you
discuss i think would be files under man/ and not doc/.
-mike