[prev in list] [next in list] [prev in thread] [next in thread] 

List:       fedora-docs-list
Subject:    Re: Lowering the participation barrier for Fedora Docs
From:       Jaromir Hradilek <jhradile () redhat ! com>
Date:       2013-11-18 23:06:08
Message-ID: 528A9D60.4050000 () redhat ! com
[Download RAW message or body]

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@fedoraproject.org - sparks@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
-- 
docs mailing list
docs@lists.fedoraproject.org
To unsubscribe:
https://admin.fedoraproject.org/mailman/listinfo/docs


[prev in list] [next in list] [prev in thread] [next in thread]