Re: Making It Easy For New Authors (was Re: Style Guide)

[hjstein@bfr.co.il (Harvey J. Stein)]

Gregory Leblanc <GLeblanc@cu-portland.edu> writes:

 > David, just as strongly as you urge use of LinuxDoc, I urge
 > acceptance of DocBook.  I'll make some comments below.

IMHO, this is exactly the sort of thing to be avoided.  It's fine to
have a prefered format (or formats).  But I think the "acceptable"
formats list should be *much* larger, and should include plain text.

<snip>

 > I don't think we want HOWTOs by people who aren't willing to take
 > some time and actually write something decent.  If they want to
 > quickly write a HOWTO, chances are that they won't have time to
 > keep it updated, or to ensure it's technical accuracy, or to
 > proofread and spell check it.

Writing something decent and marking it up nicely are two different
things.  Don't infer one from the other.  I'm sure plenty of people
are willing to generate & maintain complete and careful information,
but aren't willing to spend the additional time and suffer the
additional headaches of learning & working with a new markup language
and the associated tools.  Especially when there's controversy as to
which formats are "most" prefered.

I personally had lots of headaches with this.  I spent time learning
linuxdoc & using it to mark up my howto, only to find that a) Linuxdoc
was much too weak for my purposes, b) the tools were buggy, hard to
install, and in constant need of updating.  I ended up spending a vast
amount of time on stupid markup issues & doing dumb tweaks to make
sure that rendering in the different formats was acceptable.  I also
had a howto rejected because it was in ascii and not in Linuxdoc.  By
the time I had the time to convert it, it wasn't so relevant any
more.

So, I'd just like to vote for as large a list of acceptable formats as
possible, and that docs shouldn't be rejected for the minor technical
reason of being in an "unblessed" format (unless it's an MS Word doc :-).

-- 
Harvey Stein
Bloomberg LP
hjstein@bfr.co.il


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