At (time_t)757942953 Greg Hudson wrote:
> My experience is that consolidation of documentation often leads to
> inferior documentation in many of the places you look for it, because
> there are different standards of brevity, precision, and target audience
> in different areas of documentation.
The online help command already provides an abbreviated version
of the reference pages; the content is virtually identical
today. What this would do is eliminate the duplication of effort
that leads to errors.
Documentation isn't all that different from software in this
regard; duplication is at best a necessary evil, and I'm trying
to remove the necessity.
Furthermore, thanks to the flexible nature of XML and XSL, the
reference pages can contain enough metadata to dictate what parts
are reused for the online help, so the reference pages can expand
without forcing the online help to also grow in length.
Heck, the reference pages could include content that is _only_
displayed in the online help, so the flexibility of having online
help be worded differently from the technical reference is
maintained.
> It also leads to build systems which are hard to understand and
> which are highly sensitive to particular tool configurations.
This is painfully true, but the situation can be alleviated by
not requiring that the online help contents be regenerated from
source every time. The reference pages won't change very often.
>
> So, I'm -1 on generating the help command text from the book (if the
> book authors want to generate refentries from the help documentation,
> they can, but I think it would reduce the quality of the book). It's
> more work to maintain duplicate documentation, but it yields better
> results, and many more people are going to read our documentation than
> write it.
If man pages are not part of the final deliverable, it is very
likely that errors in the online help will be noticed by the
subversion developers, and errors in the reference pages will be
more likely to be overlooked, because the typical developer will
type "svn help <foo>" much more often than opening up a web
browser to peruse chapter 8.
Making the online help a function of the reference pages should
improve the overall quality.
--
John R. Daily
<email><mailbox>john</mailbox><domain>geekhavoc.com</domain></email>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Thu Nov 13 22:42:38 2003