Lowering the participation barrier for Fedora Docs

[Pete Travis]

On 11/18/2013 05:09 PM, Jérôme Fenal wrote:
> 2013/11/19 Pete Travis <me at petetravis.com>:
>> On 11/18/2013 04:53 PM, Eric H. Christensen wrote:
>>> On Mon, Nov 18, 2013 at 01:39:34PM -0800, Leslie S Satenstein wrote:
>>>> I would consider LibreOffice. We could have a master document and
>>> pre-assign the chapters. With markup and ability to work offline while
>>> commuting, it or a similar product would be beneficial for smaller
>>> docs or even for collaboration.
>>>
>>> With the exception of your suggestion of LibreOffice the rest is
>>> exactly what we do right now.  I see the biggest problem is creating
>>> source.  Most(?) contributors would either use vi(m) or emacs (or
>>> similar) to create the source.  There are other options as well,
>>> however.  gedit would be one of those programs that would work quite
>>> well as a GUI text editor.  LibreOffice Writer seems a bit heavy for
>>> writing source, though.
>>>
>>> I just did a quick check and it appears that LibreOffice Writer *can*
>>> save in the DocBookXML format although it's rendering is lacking.  I'm
>>> not sure it can truly support DocBookXML.  Pasting source into Writer
>>> and then saved as DocBookXML came out badly.  Working with something
>>> that isn't trying to do so much for you is better for writing code.
>>>
>>> -- Eric
>>>
>>> --------------------------------------------------
>>> Eric "Sparks" Christensen
>>> Fedora Project
>>>
>>> sparks at fedoraproject.org - sparks at redhat.com
>>> 097C 82C3 52DF C64A 50C2  E3A3 8076 ABDE 024B B3D1
>>> --------------------------------------------------
>> Of course, that doesn't mean that we can't accept content that isn't
>> marked up in a given file format.  If someone wants to take the time to
>> write an article, but they're only willing to email it to the list in
>> .odf, fine. I might be willing to convert it to docbook and fit it into
>> a guide for a new contributor, while they learn the ropes - within
>> reason.  Converting things repeatedly back and forth between any two
>> formats is going to degrade the work, and eat up a lot of time.  This
>> would be something for a mentor and protege to work out between them, at
>> the mentor's discretion.
> +1
>
> That would though that the protégé is indeed _willing_ to learn how to
> write DocBook content.

It would be *ideal* if they were eventually willing to learn DocBook. 
Still, we need to do better to make room for other forms of
contribution, whether that be filing relatively generic bug reports,
submitting content in alternative formats, or just contributing to the
discussion about why one isn't contributing to Docs. One thing that we
definitely must convey is that DocBook commits to git are the *only*
form of contribution one can perform alone; anything else requires the
active engagement of someone who can eventually do the markup and make
the commit. 

Our workflow could handle a pipeline for converting raw content to
DocBook content, but there is a line where the work required by the
second party exceeds the value of the original contribution, and I think
we should be up front about that too. I have a relative that likes to
give packages of dry ingredients and recipes as gifts; sure, I like to
eat cookies as much as the next guy, but what they're *really* giving me
is $1.23 in foodstuffs and an hour of work in the kitchen.

-- 
-- Pete Travis
 - Fedora Docs Project Leader
 - 'randomuser' on freenode
 - immanetize at fedoraproject.org


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 555 bytes
Desc: OpenPGP digital signature
URL: <http://lists.fedoraproject.org/pipermail/docs/attachments/20131118/ebd04248/attachment.sig>