Lowering the participation barrier for Fedora Docs

[Christopher Antila]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

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!"
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.19 (GNU/Linux)

iQIcBAEBCgAGBQJSiAwOAAoJEAWCcTQ3FNFMOlsP/iHkWC+azy4inSAeVDtfa+Fb
CbhahhxhbRQprIsBX0+HpzmoPcrNXttOr0uLvpy2E4oEjxMW+pG+jcd2yJKCuPyl
5KWxES0kzy6xMRGVkNsJQyL9RKqL2hCFM7t2o1LWtZFc9z9nsA2XixEsw7U3jkO2
nDXHp8g/yji5TV+t1EIOj3Vq/Tv/g/PnYloO3NOl77qDblyQ0p1WwgjJlGg6Fpeu
AZYSEMliWZEX9DqOLqFI2Z0l3hbvBlELsVXHebBoOb9YdWfLSfX7eDMupm3OPrwF
ZQmOU+xTfjOcfe0DNTj+MLHr9QJ/YExFpDaq4UfhYO1EWP9uzNQB5UhtYoIkvYj9
wYzrtShemShJtaf1bS+sgKXmw7naqwrP+fK8A3OIyOxkJXKoEUx64bJ5xf6HDJnb
NTDeqpIWAzcbaPQvF5t3r+zYFu3UdRkJZxPI7Q3M6CjtKi29sZ80WJ6QOSja4hxv
kPtn6+r8LJz61RArCq1ofzVYVNprOMOCrtf8PhU8QykEk3uDPj9kMvtBXhqzCv9A
ZPKARtF6oog4Swd+cwMUrzii1G2sZ3uIfeyP2tQYRlj60tPGLGbxPDr908TBb3MA
5ACSjoNFcGUE0pZOxrD+MU4TGKctMKyqxeiQA2VhfOLVEkEAJ26WfXN7/iFexTAI
lBo3N6Qg+iI8vrdF4+tw
=g8h7
-----END PGP SIGNATURE-----