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@xxxxxxxxxxxxxxxxx
|
