discuss: Thread: LDP needed tasks

Hello again all,

Since yesterday, two other people have expressed interest in 
volunteering, I thought yesterday a bit about the things that I have 
noticed so far in examining the current state of LDP.  I have added 
a few items to the list for what I perceive as LDP needs.

I think this list includes everything that Serge mentioned (along 
with a bit more detail).

There may be other things that we may wish to tackle.  I've made a 
list of my perceived LDP needs ordered by priority.  And, of course, 
the relative priorities, are just my opinions.

Most importantly: since we are all volunteers, I think that we 
should each tackle whatever interests us and also serves the group.

LDP Needs
---------

  * Review coordination:  One of the biggest needs we will have is 
    reviewers and review coordination.

    This role is a key role for our volunteer organization and the 
    success of the organization can be, in large measure, attributed 
    to the regular work of a person or a small group of people to 
    handle this.

    This would require a small group (or even one person) who would 
    drum the bushes to find reviewers for content and technical and 
    then follow-through so that authors were receiving feedback.

    It is precisely the review and review coordination function of 
    this volunteer group that drives the value into our 
    documentation.

    Task deliverable:  Presence and communication!

  * Acceptable formats:  We might consider accepting alternate input formats.

    A volunteer could figure out the advantages and disadvantages of 
    our accepting alternate input formats.

    We have heard from many would-be authors, volunteers and others 
    that we should support other documentation formats.  The 
    richness of the tools available to us today should allow us to 
    take alternate single-source inputs.  If the documentation 
    format can (in an automatable way) produce text, PDF, HTML 
    (single, at least; chunked would be nice), then we could 
    consider it.

    Task deliverable:  Collect suggestions (from mailing list, 
    history) for accepted formats and demonstrate conversions to LDP 
    output formats.

    Task size:  Small(-ish).

  * Script review: Review Martin's suggested publication script (and Makefile).

    I have written a script to automate generation of documentation 
    from the Linuxdoc, DocBook SGML and DocBook XML formats.  It 
    would probably be good for somebody else to review it and point 
    out errors and suboptimalities.

      https://github.com/martin-a-brown/LDP/tree/master/LDP/builder-2016

    (It is currently missing a README, but I hope to add it in that 
    directory in the next few days.)

    Task size:  Small.

  * Consistency check:  Consistency check on all LDP policy and process
    documents.  Sources: (relative to tLDP/LDP/LDP):

      faq/docbook/LDP-FAQ.xml
      howto/docbook/LDP-Reviewer-HOWTO.xml
      guide/docbook/LDP-Author-Guide/LDP-Author-Guide.xml
      http://www.tldp.org/manifesto.html
      http://www.tldp.org/jobdesc/
      http://wiki.tldp.org/LdpStaff
      http://tldp.org/vlist.html
      http://tldp.org/copyright.html
      http://tldp.org/COPYRIGHT.html

    Size:  Medium to Large.

  * Website overhaul:  We could use a public face refresh.

    The website could use a refresh--in particular, I'd think that 
    we could use some of the UX ideas of the last decade to apply to 
    the layout.  For example, I might be a user looking for a 
    particular document, a current LDP reviewer, an new author 
    hoping to submit or an existing author.  I think it could be 
    easier for each of these possible LDP users to find what s/he is 
    looking for.

    Task deliverable:  New look and/or website.

    Size:  Medium to Large.

  * Metadata format: Open Source Metadata Framework (OMF) is defunct.

    We have been (I think) using OMF to extract metadata from 
    individual documents (see our db2omf perl script [0]).  OMF was 
    related to the software project scrollkeeper [1], which has not 
    seen an update since 2002.

    In the meantime, it seems that Resource Description Framework 
    (RDF) and a derivative RDFa (expansion unknown to me) have 
    supplanted OMF.  But, there are probably other documentation 
    metadata formats.  RDFa can be embedded in DocBook XML 5 
    documents, using a separate XML namespace, so that makes it 
    attractive for the future, but it does not solve the problem for 
    our existing collection, nor for non-XML formats.

    Task deliverable:  Identify possible document metadata formats 
    and come up with a plan, and possibly, tools to allow LDP to 
    support metadata extraction from Linuxdoc, DocBook SGML, DocBook 
    XML (and any other, later supported document formats).

    Size:  Large.

  * HTML CSS file:  Create to provide consistent look of website and docs.
  
    To improve consistency of presentation between the website and 
    the documentation we publish there, it would be great to have a 
    CSS file to be imported by the generated HTML.

    Size:  Small?

Since I had started on examining (and replacing) the document 
processing system to generate the LDP output documents I ran across 
the above possible tasks. I think each task could be discretely 
handled, along with some communication and coordination on list.

That's my thought for the day,

-Martin

 [0] https://github.com/tLDP/LDP/tree/master/LDP/builder/db2omf
 [1] http://scrollkeeper.sourceforge.net/

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

Le 27/01/2016 21:04, Martin A. Brown a écrit :
> * Acceptable formats:  We might consider accepting alternate input formats.

one source that could be useful is Libre Office. A very long time ago I 
managed to convince some people to write a LibreOfice (was OpenOffice at 
the time) to export docbook. No idea where this is now.

http://www.openoffice.org/xml/xmerge/docbook/
http://www.openoffice.org/xml/xmerge/docbook/UserGuide.html

I also worked myself on some doc to have the LDP wiki produce LDP sgml

http://wiki.tldp.org/Exporting_to_docbook

by the way, my personal page on the wiki

http://wiki.tldp.org/jdd

have some interesting links.

Nota: if the LDP get some more life, I could try to refresh my own HOWTO 
around partitionning

jdd

On Wed, 27 Jan 2016 12:04:59 Martin A. Brown wrote:

<snip>
> LDP Needs
> ---------
> 
>   * Review coordination:  One of the biggest needs we will have is 
>     reviewers and review coordination.
> 
>     This role is a key role for our volunteer organization and the 
>     success of the organization can be, in large measure, attributed 
>     to the regular work of a person or a small group of people to 
>     handle this.
> 
>     This would require a small group (or even one person) who would 
>     drum the bushes to find reviewers for content and technical and 
>     then follow-through so that authors were receiving feedback.
> 
>     It is precisely the review and review coordination function of 
>     this volunteer group that drives the value into our 
>     documentation.
> 
>     Task deliverable:  Presence and communication!

I've been hoping to produce something for a while now, but I don't know
quite enough yet IMHO.
I'd be happy to review (I'm not fast though), I tend to have high
expectations though (too much documentation is incomplete), so please
don't ask unless you want the book thrown at you (and ask off list since
I don't want to spam it).

>   * Acceptable formats:  We might consider accepting alternate input
> formats.
> 
>     A volunteer could figure out the advantages and disadvantages of 
>     our accepting alternate input formats.
> 
>     We have heard from many would-be authors, volunteers and others 
>     that we should support other documentation formats.  The 
>     richness of the tools available to us today should allow us to 
>     take alternate single-source inputs.  If the documentation 
>     format can (in an automatable way) produce text, PDF, HTML 
>     (single, at least; chunked would be nice), then we could 
>     consider it.
> 
>     Task deliverable:  Collect suggestions (from mailing list, 
>     history) for accepted formats and demonstrate conversions to LDP 
>     output formats.
> 
>     Task size:  Small(-ish).

Where LDP output formats are?

<snip>
>   * Website overhaul:  We could use a public face refresh.
> 
>     The website could use a refresh--in particular, I'd think that 
>     we could use some of the UX ideas of the last decade to apply to 
>     the layout.

I'm unfamiliar with the "UX ideas".
What are you thinking of exactly?

>  For example, I might be a user looking for a 
>     particular document, a current LDP reviewer, an new author 
>     hoping to submit or an existing author.  I think it could be 
>     easier for each of these possible LDP users to find what s/he is 
>     looking for.
> 
>     Task deliverable:  New look and/or website.
> 
>     Size:  Medium to Large.

Now we need to find out what we like best for the look, feel, and layout.
Do you prefer small and simple, or big and eye candy?
There are plenty of CMS suites out there. I think if you want something
more then ultra-simple that you might use one of those.

Barrowing from the first issue (see above) Maybe add a blog to discus doc
changes, this would allow user feed back/thoughts and QA without signing
up to the mailing list. We might even improve our docs by seeing what the
users are most confused about which will inevitably change over time.

> 
>   * HTML CSS file:  Create to provide consistent look of website and
> docs. 
>     To improve consistency of presentation between the website and 
>     the documentation we publish there, it would be great to have a 
>     CSS file to be imported by the generated HTML.
> 
>     Size:  Small?
<snip>

I recommend against as some doc formats don't use css and are not sgml
derivatives. As for the main site, I'd KISS, so that users could
implement their own CSS (for example via userstyles.org). Why you ask,
the great thing about Linux is that you can hack it. We should encourage
that in our designs.

Sincerely, David

Hello David,

>>   * Review coordination:  One of the biggest needs we will have is 
>>     reviewers and review coordination.
>> 
>>     This role is a key role for our volunteer organization and the 
>>     success of the organization can be, in large measure, attributed 
>>     to the regular work of a person or a small group of people to 
>>     handle this.
>> 
>>     This would require a small group (or even one person) who would 
>>     drum the bushes to find reviewers for content and technical and 
>>     then follow-through so that authors were receiving feedback.
>> 
>>     It is precisely the review and review coordination function of 
>>     this volunteer group that drives the value into our 
>>     documentation.
>> 
>>     Task deliverable:  Presence and communication!
>
>I've been hoping to produce something for a while now, but I don't 
>know quite enough yet IMHO. I'd be happy to review (I'm not fast 
>though), I tend to have high expectations though (too much 
>documentation is incomplete), so please don't ask unless you want 
>the book thrown at you (and ask off list since I don't want to spam 
>it).

OK, great!  Thank you!  There are no outstanding review requests at 
this time.

Speed is less important than quality, so I appreciate your high 
expectations.  Of course, there is a balance to be struck when 
providing a review to a volunteer author.  TLDP wishes to cleave to 
a high standard, however we don't want to alienate the authors.

I'll correspond with you about that off list.

>>   * Acceptable formats:  We might consider accepting alternate input
>> formats.
>> 
>>     A volunteer could figure out the advantages and disadvantages of 
>>     our accepting alternate input formats.
>> 
>>     We have heard from many would-be authors, volunteers and others 
>>     that we should support other documentation formats.  The 
>>     richness of the tools available to us today should allow us to 
>>     take alternate single-source inputs.  If the documentation 
>>     format can (in an automatable way) produce text, PDF, HTML 
>>     (single, at least; chunked would be nice), then we could 
>>     consider it.
>> 
>>     Task deliverable:  Collect suggestions (from mailing list, 
>>     history) for accepted formats and demonstrate conversions to LDP 
>>     output formats.
>> 
>>     Task size:  Small(-ish).
>
>Where LDP output formats are?

LDP document output formats are:

  chunked (a.k.a. multi-page) HTML
  single-page HTML
  PDF
  text
  [We are considering adding EPUB to replace defunct Plucker.]

LDP input formats are:
   Linuxdoc
   DocBook SGML (3.0+)
   DocBook XML (4.x)+

Occasionally, we have had requests to support alternate input 
formats; commonly plain text, asciidoc, ReStructured Text.

><snip>
>>   * Website overhaul:  We could use a public face refresh.
>> 
>>     The website could use a refresh--in particular, I'd think that 
>>     we could use some of the UX ideas of the last decade to apply to 
>>     the layout.
>
>I'm unfamiliar with the "UX ideas".
>What are you thinking of exactly?

I'm thinking of anybody who has interest in giving TLDP's website a 
fresh look and a visual organizational review.

By UX ideas, I simply mean applying the ideas of user interface 
design:  our users are readers seeking documentation, authors, TLDP 
volunteers; thinking about a user's goal when designing a website.

>>  For example, I might be a user looking for a 
>>     particular document, a current LDP reviewer, an new author 
>>     hoping to submit or an existing author.  I think it could be 
>>     easier for each of these possible LDP users to find what s/he is 
>>     looking for.
>> 
>>     Task deliverable:  New look and/or website.
>> 
>>     Size:  Medium to Large.
>
>Now we need to find out what we like best for the look, feel, and 
>layout. Do you prefer small and simple, or big and eye candy?

My vote?  Small and simple.

>There are plenty of CMS suites out there. I think if you want 
>something more then ultra-simple that you might use one of those.

Yes, Serge had mentioned one particular CMS suite that he had been 
toying with.

>Borrowing from the first issue (see above) Maybe add a blog to 
>discus doc changes, this would allow user feed back/thoughts and QA 
>without signing up to the mailing list. We might even improve our 
>docs by seeing what the users are most confused about which will 
>inevitably change over time.

Before we add another arrow to the quiver, I'd ask us to examine 
whether the wiki serves this need.  If so, then no need for another 
software system.

As you mention the KISS principle below, I'd also want to adhere to 
KISS in the matters of system complexity.

>>   * HTML CSS file:  Create to provide consistent look of website and
>> docs. 
>>     To improve consistency of presentation between the website and 
>>     the documentation we publish there, it would be great to have a 
>>     CSS file to be imported by the generated HTML.
>> 
>>     Size:  Small?
><snip>
>
>I recommend against as some doc formats don't use css and are not 
>sgml derivatives.

Though most of our content is published as HTML.  

>As for the main site, I'd KISS, so that users could implement their 
>own CSS (for example via userstyles.org). Why you ask, the great 
>thing about Linux is that you can hack it. We should encourage that 
>in our designs.

I have never heard about userstlyes.org before.  I'd think that we 
could improve our visual consistency and still not interfere with 
userstyles.

My main thought here is to improve visual consistency between our 
public face (TLDP website) and the outputs of the documentation, 
using whatever tools make sense.  I grasped for CSS.  Somebody else 
may have a better suggestion.

Thanks for your message,

-Martin

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

On Fri, 5 Feb 2016 09:12:55 -0800
"Martin A. Brown" ####@####.#### wrote:

> 
> Hello David,
> 
> >>   * Review coordination:  One of the biggest needs we will have is 
> >>     reviewers and review coordination.
> >> 
> >>     This role is a key role for our volunteer organization and the 
> >>     success of the organization can be, in large measure, attributed 
> >>     to the regular work of a person or a small group of people to 
> >>     handle this.
> >> 
> >>     This would require a small group (or even one person) who would 
> >>     drum the bushes to find reviewers for content and technical and 
> >>     then follow-through so that authors were receiving feedback.
> >> 
> >>     It is precisely the review and review coordination function of 
> >>     this volunteer group that drives the value into our 
> >>     documentation.
> >> 
> >>     Task deliverable:  Presence and communication!
> >
> >I've been hoping to produce something for a while now, but I don't 
> >know quite enough yet IMHO. I'd be happy to review (I'm not fast 
> >though), I tend to have high expectations though (too much 
> >documentation is incomplete), so please don't ask unless you want 
> >the book thrown at you (and ask off list since I don't want to spam 
> >it).
> 
> OK, great!  Thank you!  There are no outstanding review requests at 
> this time.
Your welcome.

> Speed is less important than quality, so I appreciate your high 
> expectations.  Of course, there is a balance to be struck when 
> providing a review to a volunteer author.  TLDP wishes to cleave to 
> a high standard, however we don't want to alienate the authors.
>
> I'll correspond with you about that off list.
If you feel I'm being to harsh just say so. I don't feel I'm that kind of
a guy, I just read too many guides where the author uses the word
"special", or similar when describing the interesting part, the least
he could do is point me in the right direction.
I would ask that the author run aspell on his docs, it might be
a pain when using geeky words but I am *so* sick of finding stupid
spelling mistakes that could easily have been avoided.
It might be useful to distribute a list of geeky words locally. There
might be something online, let me check.....

<snip>
> >>  For example, I might be a user looking for a 
> >>     particular document, a current LDP reviewer, an new author 
> >>     hoping to submit or an existing author.  I think it could be 
> >>     easier for each of these possible LDP users to find what s/he is 
> >>     looking for.
> >> 
> >>     Task deliverable:  New look and/or website.
> >> 
> >>     Size:  Medium to Large.
> >
> >Now we need to find out what we like best for the look, feel, and 
> >layout. Do you prefer small and simple, or big and eye candy?
> 
> My vote?  Small and simple.
Mine too :)
When does the competition begin?
I'm voting for Yucky Yellow on Lime Green with Hot Pink ribbons :)
We must use three of the yuckiest colours available, everyone else does :)

> >There are plenty of CMS suites out there. I think if you want 
> >something more then ultra-simple that you might use one of those.
> 
> Yes, Serge had mentioned one particular CMS suite that he had been 
> toying with.
> 
> >Borrowing from the first issue (see above) Maybe add a blog to 
> >discus doc changes, this would allow user feed back/thoughts and QA 
> >without signing up to the mailing list. We might even improve our 
> >docs by seeing what the users are most confused about which will 
> >inevitably change over time.
> 
> Before we add another arrow to the quiver, I'd ask us to examine 
> whether the wiki serves this need.  If so, then no need for another 
> software system.
> 
> As you mention the KISS principle below, I'd also want to adhere to 
> KISS in the matters of system complexity.
Ok.

> >>   * HTML CSS file:  Create to provide consistent look of website and
> >> docs. 
> >>     To improve consistency of presentation between the website and 
> >>     the documentation we publish there, it would be great to have a 
> >>     CSS file to be imported by the generated HTML.
> >> 
> >>     Size:  Small?
> ><snip>
> >
> >I recommend against as some doc formats don't use css and are not 
> >sgml derivatives.
> 
> Though most of our content is published as HTML.  
Agreed, but I'm afraid you might be leaving some work for the team down
the road.


> >As for the main site, I'd KISS, so that users could implement their 
> >own CSS (for example via userstyles.org). Why you ask, the great 
> >thing about Linux is that you can hack it. We should encourage that 
> >in our designs.
> 
> I have never heard about userstlyes.org before.  I'd think that we 
> could improve our visual consistency and still not interfere with 
> userstyles.
Neither had I, but I was looking for and found such a site quite recently.
I'm planning on using some of their work.

> My main thought here is to improve visual consistency between our 
> public face (TLDP website) and the outputs of the documentation, 
> using whatever tools make sense.  I grasped for CSS.  Somebody else 
> may have a better suggestion.
> 
> Thanks for your message,
> 
> -Martin
> 
Hmmm, I can't think of one off the top of my head.
Question, do all the docs really need to look like the site?
The problem is that various authors across the net will have their own
guides and those guides will have their own style. Trying to get the
authors to contribute the said guide to the ldp might be a problem if
they like their style or if their doc format is, as I said above, not
sgml based.

Sincerely, David