Subject:
Re: LDP needed tasks
From:
"Martin A. Brown" ####@####.####
Date:
5 Feb 2016 17:11:54 +0000
Message-Id: <alpine.LSU.2.11.1602050848400.2025@znpeba.jbaqresebt.arg>
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/
