Subject:
Re: My rejected "replacement" for the Author Guide
From:
David Lawyer ####@####.####
Date:
6 Feb 2016 22:32:50 +0000
Message-Id: <20160206223346.GE32107@daveslinux>
On Fri, Feb 05, 2016 at 10:03:04AM -0800, Martin A. Brown wrote:
>
> Hi there David (et alia),
>
> >Almost 10 years ago I thought that our Author Guide was so long and
> >complex that it would scare away potential authors so I wrote a
> >howto on this topic.
>
> In principle, I agree. When I first contributed, I also found the
> LDP Author Guide a bit intimidating. (Later, I found the detail
> immensely helpful.)
When I came to LDP in 1998 there was no Author Guide. But there was a
3-page (printed) learn-by-examples for Linuxdoc and one just emailed in
submissions. A new leader, Lars Wirzenius, in early 1999 automated
submissions and it worked (I used it), but he resigned due to not wanting
to tolerate insults and then no one continued to implement his (beta)
automated submission system. Under Lars' system, you just emailed to a
submit address and sent your password in the clear. So LDP had simple
automatic submission 17 years ago.
>
> >It's on my website at www.lafn.org/~dave/linux/author-howto.html. >It
> was rejected by Ferguson since it is in conflict with the Guide, >which
> I referenced in the howto. I guess I was hoping that someone >else would
> volunteer to revise the Guide but I wasn't following the >list closely
> and didn't find the rejection email until years later.
>
> >So what about using it as a basis and revising the Guide to conform
> >with it.
>
> I support the notion, however, I'd turn it around a bit and rather
> incorporate your brief presentation into the LDP Author Guide.
I think that my short howto should stand on its own. The Author Guide
seems keyed towards docbook. For example in the "Markup" section it
states: The LDP uses a markup language known as DocBook. This section
doesn't yet mention wiki markup. The discussion of paragraph tags
<p> and <para> fails to mention markup which uses a blank line for
paragraph separators: linuxdoc and wikis. There is a lot of information
that an author doesn't need to know. For example, authors using wiki
markup don't need to know anything about tags using <...>. Even if the
Author Guide is revised to include more on Linuxdoc and discuss wiki
markup, I think that my howto (or the like) should stand alone and of
course reference the Guide. Perhaps the Guide should be split up, with
one doc serving as an introduction to docbook, etc. We already have my
howto: Howtos-with-linuxdoc-mini-howto. There needs to also be a doc for
how to write a wiki, including doing it offline and also using the wiki
used for Wikipedia (there are a lot of people out there who have
contributed to Wikipedia and thus already know something about its markup).
>
> Here's what I see and why I would make that choice. As an organization,
> we have two little problems that could be addressed by solving the
> problem this way:
>
> #1: we need to publish consistent information about process and
> expectations: TLDP still has (slightly) conflicting information in
> several places [see earlier emails in 2016 on this list].
>
> #2: we need a shorter introduction to being an LDP author; your
> document does that nicely
>
> Now, where would we incorporate it? I suggest the LDP Author Guide,
> specifically in the chapter/chunk which gives an overview of the LDP
> process. If we get this right, it is really all an author needs to know
> about interacting with us and what s/he can expect:
>
> http://www.tldp.org/LDP/LDP-Author-Guide/html/process.html
>
> I propose a two step incorporation and resolution of these two texts:
>
> #1: Knit your much shorter author-howto text into the existing LDP
> Author Guide.
>
> #2: Rename the section so that it's obviously something like
> "Overview" or "Quickstart" or "How do I contribute?"; once it's
> written, I'd think we would link to that canonical location from
> TLDP's web site.
>
> I'd think that this would address the question of those who wish to for
> a terse (essentially one-page) summary or overview of getting their work
> accepted into the collection and making available all of the support
> tools and recommendations that we have labored over the years to add to
> the LDP Author Guide.
>
> If you agree, David, I'd bet that Mark Komarinski or I would undertake
> the incorporation of your text. How do you feel about that?
I still think it would be better as a standalone, but OK, put it into the
Guide. I would like to see the Authors Guide changed so that it doesn't
show how to deal with docbook. How to use docbook, linuxdoc, or wikis
(such as the wiki used for Wikipedia) belongs in other howtos. If it's
to be put into the Guide, I could add paragraph tags to blank lines, but
in the past I couldn't get docbook to work on this old PC (which I'm still
using).
>
> >New acceptable formats I think should be plain text (except for
> >guides) and html. I think that there is no strong need for any doc >to
> be in all the formats we have been publishing in.
I don't think that all plain text docs will need conversion to other
formats. Just add .txt and put them on the Internet. In order to
facilitate conversion if it's needed for longer docs, we could
suggest that the author separate paragraphs by blank lines which is the
markup used by wikis and linuxdoc. Also a
heading should be required (but not necessarily marked up). Here's a
heading in linuxdoc markup:
<title> Serial HOWTO
<author>David S.Lawyer
<date> v2.28 July 2015
Note that no endtags are needed. The nice thing about using linuxdoc or
wiki is that they generate tables of contents. With no table of contents,
one can still search the text for words, but if one doesn't know much
about the topic they may not know what to search for and that's where a
table of contents is useful.
>
> Again, I have no objection to supporting alternate formats.
>
> As of today, I'm able to automatically produce outputs for all 501 of
> our Linuxdoc, DocBook SGML and DocBook XML sources. I have done some of
> the output tree cleanup preparation.
>
> I would like to improve the modularity of my automation scripts so that
> we can support alternate input formats.
>
> >Also see my linux page at www.lafn.org/~dave/linux/ I've got a
> >proposal for using a sampling review there. I think that it's more
> >efficient if just one person who understands the topic just does >one
> sampling review.
>
> I read through that. That seems OK to me. I think, as a volunteer
> organization, we can use different strategies for undertaking a review.
>
> Ultimately, any review, even a sampling review, is likely only to drive
> value into the document by addressing technical oversights, errors and
> bad advice.
The purpose of a sampling review is not to provide the author with a list
of errors since most of the errors will be missed due to sampling. Its
purpose is mainly to determine if tLDP should accept the document or if it
needs more work before accepting it. We have to be selective since when
we weren't, we wound up with documents that had negative value due to
errors (including intentional ones).
David Lawyer
