discuss: LDP needed tasks
Subject:
LDP needed tasks
From:
"Martin A. Brown" ####@####.####
Date:
27 Jan 2016 20:03:59 +0000
Message-Id: <alpine.LSU.2.11.1601270930220.2025@znpeba.jbaqresebt.arg>
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/
