[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: Pete Travis <me () petetravis ! com>
Date: 2013-11-18 23:53:46
Message-ID: 528AA88A.8030903 () petetravis ! com
[Download RAW message or body]
[Attachment #2 (multipart/signed)]
[Attachment #4 (multipart/alternative)]
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@fedoraproject.org
[Attachment #7 (text/html)]
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
On 11/16/2013 05:21 PM, Christopher Antila wrote:<br>
<blockquote type="cite">Hi:<br>
<br>
It seems to me that there are two things going on here:<br>
<br>
1.) Many of us feel we aren't doing things as well as we could be.<br>
2.) Many of us like our current tools.<br>
<br>
Let's ask ourselves "why" for both of those questions. Answers to
the first <br>
question will help us describe our problem, and to the second will
help us <br>
avoid repeating mistakes. This is my email, so I'll start.<br>
<br>
Areas We Could Improve:<br>
-----------------------<br>
<br>
- There is a significant barrier to entry. DocBook is clumsy at
first, and <br>
writing XML markup by hand is always a pain (maybe I'm just not
using the <br>
right tools). As far as I know, the only way to preview the final
output is by <br>
actually making the final output, so DocBook needs a bit of
imagination. Plus, <br>
Git is not user-friendly software and most of the documentation
out there <br>
targets people who are confident on the command-line.<br>
<br>
- The fact we try to release Guides at the same time as big Fedora
release can <br>
be very silly. The Release Notes and Installation Guide should
obviously be <br>
tied to a release, but many of the other Guides need not be. In
fact, for the <br>
Musicians' Guide, being attached to releases is
counter-productive, since <br>
audio software tends to be updated as soon as it's available, but
the Docs <br>
policy of waiting for a release discourages me from updating the
Guide when <br>
new software is published mid-release. Further, the fact I know
there are <br>
outdated sections discourages me from publishing for a new
release: it's why I <br>
didn't publish the MusGuide for Fedora 17 and 19. But again, the
Fedora 16 <br>
Guide became outdated at some point between the release of 16 and
17, meaning <br>
even the properly-numbered Guide for Fedora 16 was outdated for
more than half <br>
of its apparent lifetime.<br>
<br>
- Searching through the Guides is very difficult. Usually, you
have to know that <br>
something is there, or at least think to go looking through the
Guides, before <br>
it's possibly useful. Does Fedora have documentation for GRUB2? I
don't know, <br>
but I'd have to go looking through multiple Guides' Table of
Contents; it's <br>
easier to just check out the Arch wiki, and figure out differences
as they <br>
appear.<br>
<br>
- Every distribution's documentation has its stengths and
weaknesses. We <br>
should be trying to help, and to seek help from, these other
distributions. <br>
Even just thinking about mostly-similar distros (popular, RPM,
systemd, GRUB2, <br>
and DocBook docs), we could (and therefore should) be
collaborating and <br>
sharing with the openSUSE and Mageia communities. I mean this from
the <br>
perspectives of tools, processes, and content. We may even be able
to share a <br>
majority of content (and the translations!) across the three
distros, keeping <br>
distro-specific content in branches. Or maybe not, but it's silly
that nobody <br>
anywhere seems to have asked.<br>
<br>
What I Like about Our Current Process:<br>
--------------------------------------<br>
<br>
- Using Git. I know I said it's not user-friendly, but for the
simple tasks in <br>
the Docs workflow, if we can't write the required documentation to
help new <br>
contributors, we should all just quit! Seriously though, a robust
version-<br>
control system is essential.<br>
<br>
- Using Publican. I know I said DocBook takes a bit of learning,
but "making <br>
DocBook easy" is the job of another tool. We need to make sure we
keep using <br>
Publican for what it does well: prepare slick documents in
multiple versions. <br>
Using Publican doesn't prevent us from using additional tools
*before* <br>
Publican, like LibreOffice with a DocBook plug-in for Leslie
Satenstein, a Web-<br>
based WYSIWYG editor for my friend who noticed a typo, or a
desktop markup <br>
application for me.<br>
<br>
- Using Transifex. It's much easier than it used to be. When you
sit down and <br>
think about the benefits Transifex provides, the two additional
steps required <br>
of Guide authors are no big deal.<br>
<br>
Other Thoughts:<br>
---------------<br>
<br>
- Eric mentioned his concern over losing compatibility with
DocBook. For this <br>
reason, I'd like to draw our collective attention to the "pandoc"
tool, which <br>
converts between all kinds of markup formats, and is already
available in the <br>
Fedora repos.[0][1] If it's really good, pandoc may help us with
the "what <br>
happens before Publican" challenge.<br>
<br>
- What's the result of the mass-docs-writing experiment we ran at
FUDCon a <br>
couple years ago?<br>
<br>
- We should de-couple some Guides from the Fedora releases, and
think of a way <br>
to clearly indicate instructions for multiple versions within the
same <br>
document. We should also be careful not to lose old versions, for
archival <br>
reasons (Git!). Maybe we could just make new sections on
docs.fp.o: "Fedora" <br>
for "rolling release" Guides and "Fedora (Release-Specific)" for
others.<br>
<br>
<br>
Christopher<br>
<br>
[0] <a class="moz-txt-link-freetext" \
href="http://johnmacfarlane.net/pandoc">http://johnmacfarlane.net/pandoc</a><br>
[1] <a class="moz-txt-link-freetext" \
href="https://apps.fedoraproject.org/packages/pandoc">https://apps.fedoraproject.org/packages/pandoc</a><br>
<br>
-------------------------------------<br>
<br>
On 14 November 2013 07:58:16 Chris A. Roberts wrote:<br>
> some stuff<br>
I'm so pleased there's a "Chris A. Roberts" in Fedora, because I'm
"Chris <br>
Robert A." Now we just need is to find an "Eric Christensen
Sparks!"<br>
</blockquote>
<span style="white-space: pre;">></span><br>
First off, I feel obligated to point out that you've very nearly
written your post in functional ReStructuredText! Okay, moving
on...<br>
<br>
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!<br>
<br>
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:<br>
<br>
docs.fedoraproject.org<br>
-----------------------------------<br>
- Fedora Documentation<br>
-- Fedora 20 Release Notes<br>
-- Fedora 20 Installation Guide<br>
-- System Administrator's Guide # continuous release<br>
-- Burning ISO Images to Disc # continuous release<br>
-- etc...<br>
- Legacy Fedora Documentation<br>
-- Everything that isn't continuous release or that is targeted
to an EOL release<br>
- etc...<br>
<br>
<br>
-- <br>
-- Pete Travis<br>
- Fedora Docs Project Leader<br>
- 'randomuser' on freenode<br>
- <a class="moz-txt-link-abbreviated" \
href="mailto:immanetize@fedoraproject.org">immanetize@fedoraproject.org</a><br> <br>
</body>
</html>
["signature.asc" (application/pgp-signature)]
[Attachment #9 (text/plain)]
--
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]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic