Markup skill hoops (was re: Manisfesto)

[David Lawyer <dave@lafn.org>]

On Sat, Oct 28, 2000 at 02:23:51PM +0000, Martin WHEELER wrote:
> On Mon, 23 Oct 2000, Edward M. Corrado wrote:
> 
> > ... if a potential contributor needs to learn
> > a whole new program (to them), such as LinuxDoc or DocBook, or jump
> > through a number of hoops to submit their documentation, they might just
> > decide it is not worth the effort.
> 
> I whole-heartedly agree.  (Even though I am in favour of all authors
> eventually achieving proficiency in markup skills.  The two views are
> neither inconsistent nor mutually incompatible.)
> 
> However -- and from a purely practical point of view -- the most useful
> HOWTO information always comes from those who have struggled _hard_ to
> get something to work; have learned all the ins and outs of so
> doing; and have amassed a great deal of understanding of just what needs
> to be done, and in what order, and where the tools to do it may be found
> -- and want nothing more than to pass on their learning to others.

One may maintain a doc that someone else has written without knowing
that much about the subject.  The maintainer can incorporate
suggestions from readers (after first checking to see if they are
correct) and at the same time learn about the subject.  So I would say
that having someone maintain a doc with some understanding of the
topic is better than having no one at all maintain it.

> And THAT is what the LDP requires.
> 
> Not, I am afraid, a beautifully marked-up chunk of text.  

I agree that improving the quality and scope of the docs is a lot more
important than excellent markup.  However all docs should have a
table of contents.  This is automatically created by the markup.  In
fact, using a LinuxDoc simple markup is actually easier than just
using plain text (I've tried both).   This is because using such a
markup is easier than doing the table of contents manually (including
the work to manually number the sections and subsections).

> (Which, incidentally, may take a further six months to produce). 

Unlikely.  I claim one can learn to use a minimal LinuxDoc markup in
just a few hours.  It may also take an hour or two programming ones
editor so that just hitting a couple of keys inserts a tag.  What one
learns by doing this can be of value in learning other markup
languages and in creating editor "macros".

> 
> So my advice to all would-be authors/HOWTO writers is this --
[snip]
> announce its availability via this list (or make it available on
> some web-site or other); request editorial assistance for its
> conversion to SGML/any other required format; then wait for
> comments.
> 
> If you don't get any comments, either no-one's interested in the
> topic

Not so.  There could be thousands of people interested, but no one on
this list may have that interest.  But sometimes a proposed HOWTO
may fall outside the scope of LDP and belongs elsewhere. 

, or no-one's interested in the writing.  If you don't get
> conversion, then none of the available editors could find the
> time/energy (we're all over-extended).
> 
> In any case, it's no longer your problem -- let the mandarins deal
> with it from there on in.

Yes it is your problem.  It may need rewriting.  You should take a
look at LinuxDoc source.  Perhaps you can cope with it.  If it's
outside the scope of LDP, perhaps you could submit it elsewhere.

			David Lawyer


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org