[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:       "Eric H. Christensen" <sparks () fedoraproject ! org>
Date:       2013-11-18 15:05:47
Message-ID: 20131118150546.GA17208 () localhost ! localdomain
[Download RAW message or body]

-----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.

> - 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.

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-----
-- 
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]