An interesting blog by Matt Zimmerman touches on docs

[Kyle Nitzsche]

Hi Andrew and all,

On 07/12/2010 07:03 PM, Andrew Kane wrote:
> Web-based help is a good idea for new-user documentation and for user
> docs in general, but it can't effectively be closely coupled to the
> user's OS version or package set.
I'd like to comment on this idea of documentation being closely couple 
to the "package set". Given how many variants of Ubuntu there are now 
and that there will be ever more, I don't think it makes practical sense 
to couple docs to a package set. Doing so builds dependencies and 
therefore inflexibility where there doesn't seem to be a compelling 
reason to do so. I tend to think a better approach is help as short and 
non-interdependent articles (that is, no links between them). Any 
'linking' can/should be done in the portal that presents them (whether 
is a web page or on-disk help) in order to facilitate delivery of help 
content in the wildly modularized and multi-flavored real world of Ubuntu.

> Because of this some of the help
> will necessarily be inaccurate.
> Also, user-based help is not the only help. As a sysadmin I make
> constant use of various manpages.
Man pages should be on disk, I think, although perhaps they should only 
be optionally present (requires user action to install) in order to 
preserve precious disk space.
>   (Some may argue that this means I'm
> a rather poor sysadmin, but that's neither here nor elsewhere.) It's
> very important in my opinion that at minimum, local documentation
> should include manpages in *every* package, as part of that package,
> and those manpages should be edited so that the information contained
> is pertinent to the particular build in the package. I've often run
> into manpages that refer to options which are not implemented or to
> configuration files which are located elsewhere than the path shown.
> Manpages are relatively small chunks of ASCII- I'd be surprised if
> there were a manpage extant that runs to more than 50KB- and therefore
> shouldn't add excessively to the size of the package. On the other
> hand, the ubuntu-docs  package is 270MB, 90% of which I will never
> read.
> I understand that in many cases manpages need to be bundled together
> as in the manpages package which contains man4, 5, and 7. Also, it's
> not necessarily reasonable to expect all package maintainers to also
> maintain these manpages- but perhaps that is something the docs team
> could help with. I would certainly be willing to offer my time to help
> with that. Manpages are relatively easy to edit.
>
>    
Cheers,
Kyle