Docs CMS Idea - docs - Fedora mailing-lists

25 Jun 2010

      Hello:
I have some comments about the (G)UI aspect of the CMS ideas floating
around.  Imagine that everything following is prefixed with the "in my
experience," "in my opinion," or "as a new/prospective docs
contributor," warning.
Quaid:
...
While Publican gives us a way to build a nicely organized tree of
content, it doesn't give other capabilities.  I don't know of any
plans to include this sort of thing in Publican natively:

Ability to trigger (re)builds from source repositories via a webUI.
Workflow control, either by group (writers, editors, publishers), or

specific roles like that but per document (I can write this one, I
 can edit yours, and I can push hers to publish after you edit it.)

WYSIWYG editor for DocBook XML from source repository.

Having to learn fifteen (or even three) completely different programs
before being able to contribute is discouraging.  It's also somewhat
irrelevant how difficult it is to learn those programs, because new
contributors are going to be afraid of making mistakes.
Quaid:
...
Basically, we still have very high barriers to move from "edit stuff
on the wiki" to "manage a full guide on DocBook XML."  The main
purpose for a CMS is to get the ability to publish and tweak
docs.fedoraproject.org out of the hands of a very few, very busy
people, and in to the hands of just about anyone that this team wants
to authorize to do work there.
That barrier is very real.  If you want something that will allow a lot
of people to contribute to the publishing effort, then it's going to
have to be easy.  Furthermore, technical barriers should only exist for
things actually related to the writing process.  That is to say, the
fact that I don't already know how to use git shouldn't stop be from
contributing to a guide - it should be the fact that I don't already
know the program I'm going to write about.
Quaid:
...
This proposal exists partially because of our commitment to using
Publican to publish.
I ask this out of ignorance for the docs process and without any real
idea of what Publican is or what it does: why are we using it?  I'm sure
there's a good reason, but "But we're using Publican!" seems to be the
reason that Docs doesn't already have a CMS.
Quaid:
...
Functions:
...
0. Read
What we do here has to look good, and it has to be easy to use.  I'm
tempted to say that this particular aspect of the documentation process
shouldn't be left to the Docs team at all.  Writers of documents should
be focussed on the content of those documents.  Leave all the
typesetting and other business to people who are focussed on that.  Docs
could bring in (or maybe already has) some people focussed on this, but
maybe another Fedora SIG is better-suited to document presentation than
Docs is.
I would personally at least like to see visual integration with the rest
of the Fedora Project website.  Currently the docs website is one of the
many confusing sub-worlds of FP, and it looks, frankly, cold and unhelpful.
More importantly, it must be easy to use.  The new Docs website is
definitely an improvement over the old one, but it still doesn't answer
questions that I ask of it quite often, like:
1.) What happened to the content of F12's Deployment Guide?
2.) What's the difference between the SELinux guides?
3.) What's the difference between "Managing Confined Serivces" and
"Security?"
4.) Why are there tips for SELinux in "Managing Confined Services?"
5.) Where is the answer to my question?
6.) My question isn't answered here, so now what?
These are not problems with the guides themselves, but with the
Publican-created website that offers no help in finding help.  Sure,
there's a search box, and sure I could answer those questions by reading
the documents and comparing, but I think we can do better.  I only
resort to a search if I can't guess my way through a site.
Here's what I'd like to see as a user:
1.) I need help.
2.) I go to fedoraproject.org
3.) I click "Get Help," and somehow decide that "Documentation" is right
for me (it should be advertised better).
4.) I'm greeted by a visual/written organizer that helps me see which
guide I want.
5.) My web browser automatically detects which version of Fedora I'm
using, or else I am asked, and provided a list with the
currently-supported versions displayed and an "other versions" button to
access documentation for not-currently-supported versions.
6.) If I can't find the answer to my problems, I get directed back to
the "Get Help" page, or to upstream documentation.
All the while, the familiar fp.o website look and feel has stayed the
same, as seen in the top and left portions of this page:
http://fedoraproject.org/en/get-help
Quaid:
...

Write/edit

This is a task separate from reading documents, so we can use a
different application.  My preference is for an extension to an existing
text editor, that:
-incorporates well-known text-editing features,
-incorporates DocBook XML help,
-incorporates fast/easy ways to get and commit what you've been working on.
Emacs could accomplish these things, but it's not a great solution.
Contributors would have to learn how to use emacs first, and then learn
how to use the Docs extensions to emacs.  Emacs is not easy to use, or a
friendly application.  It terrifies me.
This could be written as an extension or plugin for GEdit, but again I
don't feel this is a great solution.  Users might feel like they need to
learn two things (like with an emacs extension), and they might rightly
feel like they aren't being provided with a fully-customized,
Docs-tailored experience.  Of course, they're right about that - other
things go on in GEdit, too.
My preference would be for an editor incorporating the KWrite KPart.  I
don't know the details of this, but it might have dependencies in KDE,
which makes this choice much less attractive for a GNOME distribution.
They may or may not be that troublesome.  Here are some benefits to this
approach:
-it will result in a fully-customized application; users might not even
notice that it's built primarily with KPart's
-you can incorporate many different KPart's: like the web-browsing one,
which would allow you to use some web-based interface, or view DocBook
XML help files online; or the PDF-viewing one, which would allow you to
preview a PDF version of what you're working on
-users will feel like they need to learn only one thing, but we can also
take advantage of the fact that they'll instinctively be able to use the
KPart's
-the application basically already exists, and most of it would be
maintained for us by upstream KDE developers
It just seems so much more attractive to me to use a Publican front-end
called "Publican" than to have to start GEdit, turn on Publican mode,
and still have to use external applications to preview my work, or to
get help.
Quaid:
...

Publish

A much smaller number of people will be publishing, compared to the
number writing and editing.  The publishing tasks could be incorporated
into a text-editing GUI, but since you're just moving things around on
the internet, it makes more sense to use a web-based application for this.
I hadn't intended to advocate against a CMS, but it looks like I will.
"The Unix(TM) Way" is to build tools that do one thing well, and combine
them into things that accomplish Useful Work.  This is what would be
happening with a KPart-based GUI editor.  Keeping with that same line of
thought, it doesn't make sense to use a single (web-based) tool to do
three different tasks: reading, writing, and publishing.  These are
distinctly different tasks, so we should use distinctly different tools.
 Moreover, this separation will help us to tailor each tool to its
specific task.
Most people who use the official documentation will not be writing them,
and the official documentation should look professional/official.  It's
not a wiki.  The goal, as I understand it, is to make the barrier for
entry as low as possible, but it can't be seen as too low, or else it
discredits the project.  I don't think we were at imminent risk of that,
but it's something to consider with a CMS.
The nice thing about this is that the Docs SIG already has a working
process, and already produces the best documentation of any Linux-based
operating system.  It was the Four Fs that brought me to Fedora, but it
was the quality of the documentation that made me stay.
Christopher.