discuss: wanted: a really good case for LinuxDoc
Subject:
Re: wanted: a really good case for LinuxDoc
From:
David Lawyer ####@####.####
Date:
9 Dec 2003 19:36:52 -0000
Message-Id: <20031209193608.GB571@lafn.org>
On Tue, Dec 09, 2003 at 11:46:17AM -0500, Emma Jane Hogbin wrote:
> Hey all,
>
> I'm working on the Author Guide (still, again, etc). I need a really
> easy-to-understand, simple, (etc) reason why newbie authors should choose
> LinuxDoc over DocBook.
>
> David's document: http://tldp.org/HOWTO/Howtos-with-LinuxDoc.html
> is missing something. I'm not entirely sure what it is though...I think
> it's because the format is so close to the Author Guide.
>
> thanks,
> emma
> PS This is not the time/place to say anything about the /merits/ of
> LinuxDoc. The Author Guide is /heavily/ biased towards DocBook, and I just
> want to add a little, "hey -- you can use this instead" every now and
> then.
The reasons why authors should use LinuxDoc are the same as the merits
of LinuxDoc. You can't separate the two. So I'll discuss the merits.
LinuxDoc merits:
1. A lot less time to learn
2. Much easier to type (shorter and fewer tags)
3. Easier to read (for example, no tags for paragraphs)
4. Less problems with the software
Favoring DocBook is that the additional tags help in semantic analysis of
the doc and in extracting metadata, etc. But I would argue that this
advantage isn't utilized that much and (and will not be very significant
in the future either, due to developments in AI). Thus, in my opinion
the benefit/cost ratio for using DocBook over LinuxDoc is not high
enough to justify the use of DocBook for those who don't already know
it.
While such benefit/cost ratio for using DocBook (over Linux Doc) may be
higher than unity, this doesn't mean that one should do it, since by
spending time updating docs, etc., the benefit/cost ratio is often many
times greater than unity. In volunteer work, if one wants to give the
most benefit to the public, one picks the tasks that have the highest
benefit/cost ratio.
I suggest that at the very start of the Author Guide, you present the
option of LinuxDoc and suggest that if they opt for LinuxDoc, then they
may not need to read any further. This way, they can get started
writing much sooner.
David Lawyer
