[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: Single source documentation

From: Greg Hudson <ghudson_at_MIT.EDU>
Date: 2003-11-13 19:45:21 CET

On Wed, 2003-11-12 at 00:01, John R. Daily wrote:
> Earlier this year, the problem of documentation duplication was
> discussed on this list, but apparently nothing ever came of it.
>
> This evening, I've been experimenting with a process to generate
> the help command text from the refentries in the book, and I have
> an alpha-quality solution.

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. It also leads to build systems
which are hard to understand and which are highly sensitive to
particular tool configurations.

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.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Thu Nov 13 19:48:47 2003

This is an archived mail posted to the Subversion Dev mailing list.