Lowering the participation barrier for Fedora Docs

[Pete Travis]

On 11/16/2013 05:21 PM, Christopher Antila wrote:
> Hi:
>
> It seems to me that there are two things going on here:
>
> 1.) Many of us feel we aren't doing things as well as we could be.
> 2.) Many of us like our current tools.
>
> Let's ask ourselves "why" for both of those questions. Answers to the
> first
> question will help us describe our problem, and to the second will
> help us
> avoid repeating mistakes. This is my email, so I'll start.
>
> 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.
>
> - 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.
>
> - 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.
>
> - Every distribution's documentation has its stengths and weaknesses. We
> should be trying to help, and to seek help from, these other
> distributions.
> Even just thinking about mostly-similar distros (popular, RPM,
> systemd, GRUB2,
> and DocBook docs), we could (and therefore should) be collaborating and
> sharing with the openSUSE and Mageia communities. I mean this from the
> perspectives of tools, processes, and content. We may even be able to
> share a
> majority of content (and the translations!) across the three distros,
> keeping
> distro-specific content in branches. Or maybe not, but it's silly that
> nobody
> anywhere seems to have asked.
>
> What I Like about Our Current Process:
> --------------------------------------
>
> - Using Git. I know I said it's not user-friendly, but for the simple
> tasks in
> the Docs workflow, if we can't write the required documentation to
> help new
> contributors, we should all just quit! Seriously though, a robust version-
> control system is essential.
>
> - Using Publican. I know I said DocBook takes a bit of learning, but
> "making
> DocBook easy" is the job of another tool. We need to make sure we keep
> using
> Publican for what it does well: prepare slick documents in multiple
> versions.
> Using Publican doesn't prevent us from using additional tools *before*
> Publican, like LibreOffice with a DocBook plug-in for Leslie
> Satenstein, a Web-
> based WYSIWYG editor for my friend who noticed a typo, or a desktop
> markup
> application for me.
>
> - Using Transifex. It's much easier than it used to be. When you sit
> down and
> think about the benefits Transifex provides, the two additional steps
> required
> of Guide authors are no big deal.
>
> Other Thoughts:
> ---------------
>
> - Eric mentioned his concern over losing compatibility with DocBook.
> For this
> reason, I'd like to draw our collective attention to the "pandoc"
> tool, which
> converts between all kinds of markup formats, and is already available
> in the
> Fedora repos.[0][1] If it's really good, pandoc may help us with the
> "what
> happens before Publican" challenge.
>
> - What's the result of the mass-docs-writing experiment we ran at
> FUDCon a
> couple years ago?
>
> - We should de-couple some Guides from the Fedora releases, and think
> of a way
> to clearly indicate instructions for multiple versions within the same
> document. We should also be careful not to lose old versions, for
> archival
> reasons (Git!). Maybe we could just make new sections on docs.fp.o:
> "Fedora"
> for "rolling release" Guides and "Fedora (Release-Specific)" for others.
>
>
> Christopher
>
> [0] http://johnmacfarlane.net/pandoc
> [1] https://apps.fedoraproject.org/packages/pandoc
>
> -------------------------------------
>
> On 14 November 2013 07:58:16 Chris A. Roberts wrote:
> > some stuff
> I'm so pleased there's a "Chris A. Roberts" in Fedora, because I'm "Chris
> Robert A." Now we just need is to find an "Eric Christensen Sparks!"
>
First off, I feel obligated to point out that you've very nearly written
your post in functional ReStructuredText!  Okay, moving on...

The idea of accepting contributions in varying formats then converting
them for publishing is definitely worth investigating.  Let's add
"Identify formats that can be converted to DocBook with fedora-shipped
tools" to the list!

The idea of rolling release documentation is growing on me, as I
consider it.  There's no reason to hold back from publishing something
as soon as the feature hits the repos. If we work with a continuous
release model we'll ship updates to Guides that lag behind release date
instead of waiting for the next release.  If we're coordinating
efforts,  it might be more intuitive to focus effort on features than
release number as well.  I wonder if we can get something like this:

docs.fedoraproject.org
-----------------------------------
- Fedora Documentation
    -- Fedora 20 Release Notes
    -- Fedora 20 Installation Guide
    -- System Administrator's Guide # continuous release
    -- Burning ISO Images to Disc # continuous release
    -- etc...
- Legacy Fedora Documentation
    -- Everything that isn't continuous release or that is targeted to
an EOL release
- etc...


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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.fedoraproject.org/pipermail/docs/attachments/20131118/df753be6/attachment.html>
-------------- 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/df753be6/attachment.sig>