An interesting blog by Matt Zimmerman touches on docs
Kyle Nitzsche
kyle.nitzsche at canonical.com
Tue Jul 13 15:07:29 UTC 2010
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
More information about the ubuntu-doc
mailing list