Lowering the participation barrier for Fedora Docs

Mon Nov 18 23:06:08 UTC 2013

On 11/18/2013 04:05 PM, Eric H. Christensen wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA512
>
> On Sat, Nov 16, 2013 at 07:21:30PM -0500, Christopher Antila wrote:
>> Areas We Could Improve:
>> -----------------------
>> - There is a significant barrier to entry. DocBook is clumsy at first, and
>> writing XML markup by hand is always a pain (maybe I'm just not using the
>> right tools). As far as I know, the only way to preview the final output is by
>> actually making the final output, so DocBook needs a bit of imagination. Plus,
>> Git is not user-friendly software and most of the documentation out there
>> targets people who are confident on the command-line.
>
> I guess so many of us just use the CLI to create our works that we don't think about GUI programs.  I couldn't tell you a single GUI program that would be good for creating/editing DocBook (gedit?) because I just don't use them.  I'd welcome other people's experience with GUI tools so we can start recommending these to people.  Same goes for Git.  It really isn't that difficult to use these tools once you understand what's happening and why.  Like I mentioned earlier, I think training is key here and something we're missing.  Last week I started working on training videos that I'll continue to refine (I'm still sick so my voice isn't great right now).  As soon as they are ready I'll start kicking them out the door and hope to get feedback.

Gedit has built-in support for DocBook and is shipped with a complete 
set of snippets for this language. I don't think it can do much more though.

Vim users can use two of my plug-ins: enhanced DocBook support with 
updated syntax file, improved auto-detection, and omni-completion for 
both DocBook 4.5 and 5.0 (omni-completion is something like DTD-aware 
editing), and my complete set of snippets for DocBook 4.5:

- https://github.com/jhradilek/vim-docbk
- https://github.com/jhradilek/vim-snippets

My configuration file for Vim can be found here:

- http://www.blackened.cz/dotfiles/.vimrc.html

Emacs users with nxml-mode enabled can use my complete set of snippets 
for DocBook 4.5:

- https://github.com/jhradilek/emacs-docbook-snippets

Similarly, my configuration file for Emacs can be found here:

- http://www.blackened.cz/dotfiles/.emacs.d/init.el.html

>> - The fact we try to release Guides at the same time as big Fedora release can
>> be very silly. The Release Notes and Installation Guide should obviously be
>> tied to a release, but many of the other Guides need not be. In fact, for the
>> Musicians' Guide, being attached to releases is counter-productive, since
>> audio software tends to be updated as soon as it's available, but the Docs
>> policy of waiting for a release discourages me from updating the Guide when
>> new software is published mid-release. Further, the fact I know there are
>> outdated sections discourages me from publishing for a new release: it's why I
>> didn't publish the MusGuide for Fedora 17 and 19. But again, the Fedora 16
>> Guide became outdated at some point between the release of 16 and 17, meaning
>> even the properly-numbered Guide for Fedora 16 was outdated for more than half
>> of its apparent lifetime.
>
> I am unaware of the policy you referenced.  We *do* want guides to be published when a release is made so that users will know that the guide is specific to that release and that information isn't old or not applicable (although once we get a huge guide together there will always be old stuff in there) but a continued development should go on.
>
> I'll use the Amateur Radio Guide as an example.  If I, today, package a new amateur radio program I'll more than likely add it to the guide and re-release the current guide with a later version.  That's completely acceptable and desired (release early, release often!).  If something changes mid-stream please update your text!
>
>> - Searching through the Guides is very difficult. Usually, you have to know that
>> something is there, or at least think to go looking through the Guides, before
>> it's possibly useful. Does Fedora have documentation for GRUB2? I don't know,
>> but I'd have to go looking through multiple Guides' Table of Contents; it's
>> easier to just check out the Arch wiki, and figure out differences as they
>> appear.
>
> There is definite overlap in some of the guides (installation, admin, and security to name a few).  We should probably reduce that overlap and make sure the expectation is to find a certain piece of information in a certain guide.  Getting an internal search engine going is also needed.

We are trying to reduce the overlap between the System Administrator's 
Guide and Installation Guide, but it is a slow process, because both 
these books are quite old and large.

> There are lots things that need to be done, really.  I suspect that it would be quite a lift to get us back to where we need to be.  That said, I don't think it's out of the question.  Would people be interested in meeting for a FAD to get some stuff done?
>
> - -- Eric
>
> - --------------------------------------------------
> Eric "Sparks" Christensen
> Fedora Project
>
> sparks at fedoraproject.org - sparks at redhat.com
> 097C 82C3 52DF C64A 50C2  E3A3 8076 ABDE 024B B3D1
> - --------------------------------------------------
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.15 (GNU/Linux)
>
> iQGcBAEBCgAGBQJSiizHAAoJEB/kgVGp2CYvDdAL/2kuN5XaUQRchMKQBky4icxW
> wqHZ4qdlCx8tGKSmj8XEdo1zeTLebFkc988/pRHHDtEEEbVwrpJhhZS5t3s9htbN
> mYlQuGb7BGx01GSRScHc+lDwZSwO0tgcpfQ/omhVBzXi5TJlyktff4uOkcNoQwqw
> We2gPx/1+4b7ahcV2FDwrdBYIks3+VZaZ1FCr5bxjJuwszC2exoXHgcC1UEReniA
> Pbtga4l39VtfBXGDpZCx3MJiis2Wth0uxR3a2o1BEuzB8o7Jl3pgGHrtcB8U8d4/
> L+WZ/6ARfip2E/N1NAFgmgqTDZWBnhkzQ22YWS7IJO+P6bRCwUoSq1RGj7lda0Lz
> RYdmPg2KTbm1DsPV/r9VIplv53ohGQStArT0xOt/pY5DrMMAUaqedxpyO3GcH51p
> rNemTk5ZxKnqoHdsq9ZeGqya0ZtUzD1TqEw6tEWrcfGs9ctK4PuBBFqI3fOxTVhY
> /x9uomENbCt/HDZHsd1zGxIOMhTQc9XA87UPtdcsSg==
> =/maF
> -----END PGP SIGNATURE-----
>

-- 
Jaromir Hradilek
Supervisor, Content Services

Red Hat Czech, s. r. o.
Purkynova 99
612 45 Brno, Czech Republic