discuss: Thread: My rejected "replacement" for the Author Guide

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
the top.  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.  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.

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.  The
two review process was created by LDP since some people in LDP didn't know the
technical aspects very well.
				David Lawyer

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 the top. 

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.)

>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.

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?


>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.

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 two review process was created by LDP since some people in LDP 
>didn't know the technical aspects very well.

I see.  I did not know that.  I guess that's something for our 
review coordinator to think about!

Good suggestions and thank you,

-Martin

-- 
Martin A. Brown
http://linux-ip.net/

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

Hello and good morning,

>> >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.

Ah, interesting.  Neat.

That reminds me of the first-generation of tools for whois domain 
and Internet number resource management.  There was an email gateway 
that would handle change requests.  In the late 1990s, this fell by 
the wayside because of ease of abuse.  [Some used cryptographic 
tools to secure the content and provide authorization, but 
eventually, web applications and interfaces riding on HTTP 
supplanted this.]

>>   #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.
>>
>> 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. 

I see your point here about separating the process/policy content in 
the LDP Author Guide from the technical matters, which will differ 
depending on format and tooling.

I'd hate to remove the good DocBook information from the LDP Author 
Guide, but if we are going to accept multiple formats, it would be 
good to examine the LDP Author Guide to see where we could 
de-emphasize DocBook, while retaining the valuable information for 
those who do choose DocBook.

Mark:  Any objections to some adjustment of LDP Author Guide along 
those lines?  I'd be happy to volunteer to read, suggest and 
possibly provide patches, if you would like.

>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).

OK.  It's like the old comfortable pair of socks!

>> 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).

Right.  Absolutely understood.

-Martin

-- 
Martin A. Brown
http://linux-ip.net/

On 2/9/2016 10:59 AM, Martin A. Brown wrote:
>> 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.
> Ah, interesting.  Neat.
>
> That reminds me of the first-generation of tools for whois domain
> and Internet number resource management.  There was an email gateway
> that would handle change requests.  In the late 1990s, this fell by
> the wayside because of ease of abuse.  [Some used cryptographic
> tools to secure the content and provide authorization, but
> eventually, web applications and interfaces riding on HTTP
> supplanted this.]
I started the LAG after trying to figure out how DocBook worked. I'll 
admit my bias towards a cleaner and richer format, but not everyone 
shares my opinion and I'll have to deal with it ;)
> I see your point here about separating the process/policy content in
> the LDP Author Guide from the technical matters, which will differ
> depending on format and tooling.
>
> I'd hate to remove the good DocBook information from the LDP Author
> Guide, but if we are going to accept multiple formats, it would be
> good to examine the LDP Author Guide to see where we could
> de-emphasize DocBook, while retaining the valuable information for
> those who do choose DocBook.
>
> Mark:  Any objections to some adjustment of LDP Author Guide along
> those lines?  I'd be happy to volunteer to read, suggest and
> possibly provide patches, if you would like.

No problem there.  It looks like there's a link to the 
'Howtos-with-LinuxDoc-mini-HOWTO'.  Maybe break the various acceptance 
formats into their own HOWTOs and have the LAG link to each of those and 
then document the LDP processes?  It'll be a lot of work but will allow 
each person with their own their own space to list the features and use 
of their particular format.

-Mark