| 1 |
On Monday, November 29, 2010 18:59:04 Daniel Barkalow wrote: |
| 2 |
> On Sat, 27 Nov 2010, Zac Medico wrote: |
| 3 |
> > On 11/27/2010 01:25 AM, Sebastian Pipping wrote: |
| 4 |
> > > In case DocBook is keeping contributions down than cutting away certain |
| 5 |
> > > flexibility to increase contributions could be a good trade-off, too. |
| 6 |
> > |
| 7 |
> > I'm not sure that docbook represents a significant barrier in this |
| 8 |
> > respect. It's hard to speculate. Maybe if we had a survey sampling the |
| 9 |
> > opinions of a broad spectrum of open-source developers, then we'd have |
| 10 |
> > more to go on. |
| 11 |
> |
| 12 |
> My impression from git development is that, with asciidoc, we got a lot of |
| 13 |
> documentation patches from users who read the documentation, found that it |
| 14 |
> was inaccurate or unclear, and were able to propose corrections based on |
| 15 |
> their observation of the actual behavior. I believe we also got |
| 16 |
> documentation of previously undocumented functionality, written by people |
| 17 |
> who had found out how to use it from some other source after failing to |
| 18 |
> find it mentioned in the documentation. I suspect that docbook is too high |
| 19 |
> a barrier for some people when asciidoc wouldn't be; the question is |
| 20 |
> really whether any of these people are the audience for portage |
| 21 |
> documentation. |
| 22 |
|
| 23 |
all of the user-facing documentation is in the man pages. all of the docbook |
| 24 |
pages are generally more internal stuff. so any of the corrections you |
| 25 |
discuss i think would be files under man/ and not doc/. |
| 26 |
-mike |
Archives