Docs CMS Idea

Sun Jun 27 00:01:22 UTC 2010

On 06/26/2010 06:45 AM, Christopher Antila wrote:
> 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.
>    

Thanks Christopher for the detailed feedback and suggestions; I'll 
respond to a few points in line with regard to the publishing side:

> 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?

Publican is a publishing tool, designed to operate "end-to-end" by 
taking a single source of XML files (combined with translations in PO 
format) and publishing content in multiple formats on the web and on 
users' local systems.

Publican does two jobs for Docs:

* For the last 18 months or so, we've been using Publican to render the 
XML files into single-page HTML, multiple-page HTML, and PDF in all the 
languages that we publish. Previously, we then took this output, 
transferred it manually into a local copy of the docs file hierarchy 
(creating new directories as necessary), added or updated some 
hand-edited PHP menu files (there were over 40 to keep in sync), and 
manually performed a series of steps to check the results into a 
CVS-controlled repository that would then appear on the web server.

* For the last 2 months or so, we've used Publican's new in-built 
publishing feature to replace the hand-editing. Publican now not only 
generates the documents, but places them into a consistent file 
hierarchy, and automatically regenerates tables of contents in all the 
languages in which we publish. This change happened concurrently with 
the Fedora Infrastructure team moving us from using CVS to upload the 
results to the webserver to using Git to do that job.

Currently, we're working towards implementing the final piece of the 
puzzle: fully automating the document build and publish process. This 
means that anyone with the appropriate permissions can build and publish 
a new version of a document with two commands at the command line and 
avoid interacting with any version-control system.

I also rather like Ryan Lerch's introductory infographic for Publican 
(and wish he would make more of it!)[0]

> 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.
>    

Not really. Over at least the last 18 months, the docs team has been 
looking for a way to replace manually creating directories and 
hand-coding menus -- which was a temperamental, error-prone, and 
unforgiving process -- with an easier way of publishing built content on 
the web. So work on packaging the Zikula CMS started, but is still not 
quite complete.

In the meantime, Red Hat made Publican's publishing components openly 
available for the first time, which do the same job as the core 
functionality for which we were looking to a CMS.

So the two questions now are:

* what would a CMS offer us that Publican's built-in publishing 
components don't? (the subject of this current thread)

* if the CMS could not build and publish documentation as easily and 
efficiently as Publican, would those other benefits outweigh the 
disadvantages in the core functionality?

> 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.

To a large extent, it's not. The visual styles of d.fp.o come from 
Publican, which is developed with input from the Fedora docs team, Red 
Hat Engineering Content Services, and a steadily-growing community of 
users in other projects and distros. Fedora docs is currently the 
largest and most publicly visible user though.

> 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.

I honestly don't see this as any big deal; but if others felt it was 
desirable, this should be possible by post-processing the html output on 
the web server itself.

> Currently the docs website is one of the
> many confusing sub-worlds of FP, and it looks, frankly, cold and unhelpful.
>    

Please raise this on the Publican mailing list.[1]

> 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?
>    

It's still there.[2]

We didn't publish a Deployment Guide for Fedora 13, but hopefully we 
might publish one for Fedora 14. If you want to get the current status 
of the Deployment Guide, you should contact the project lead.[3]

There's no guarantee that we'll publish any particular guide in any 
particular language for any particular Fedora release. Users can 
probably count on a set of Release Notes and an Installation Guide in 
English, but anything else is completely subject to the availability of 
writers and translators.

> 2.) What's the difference between the SELinux guides?
>    

Each of our guides contains an abstract that should provide a helpful 
description of its contents. If the abstract for any particular guide 
doesn't make the contents of the guide clear, then you should file a bug 
against that guide.

> 3.) What's the difference between "Managing Confined Serivces" and
> "Security?"
>    

Again, the abstracts should make that clear.

> 4.) Why are there tips for SELinux in "Managing Confined Services?"
>    

I think that the abstract of the Fedora 13 Managing Confined Services 
Guide makes this really clear:

"The Managing Confined Services guide is designed to assist advanced 
users and administrators when using and configuring SELinux. It is 
focused on Fedora Linux and describes the components of SELinux as they 
pertain to services an advanced user or administrator might need to 
configure. Also included are real-world examples of configuring these 
services and demonstrations of how SELinux complements their operation." 
[4]

> 5.) Where is the answer to my question?
>    

That rather depends on the question! If the question is 
installation-related, then the Installation Guide would be a logical 
place to start; if it's security-related, the Security Guide would be a 
logical place to start. Hopefully most of our titles are 
self-explanatory, but please feel free to suggest new titles for any 
guides that you think are not.

> 6.) My question isn't answered here, so now what?
>    

Many guides have lists of further resources or reading, and *all* guides 
contain a link with an invitation to provide feedback on how we can do 
better.

> These are not problems with the guides themselves, but with the
> Publican-created website that offers no help in finding help.

Well, possibly. But in many cases, it's also possibly the fault of the 
guy who wrote the Welcome page (me!) Publican doesn't determine the 
content here at all. If you have specific recommendations for things 
you'd like to see included, please raise them here -- I'd be very 
grateful for suggestions or feedback.
> 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).
>    

That's something to raise with the websites team; we have no control 
over that.

> 4.) I'm greeted by a visual/written organizer that helps me see which
> guide I want.
>    

I looked at implementing that on the Welcome page (based on the 
abstracts of the individual guides). Indeed, we did just that on the 
previous incarnation of the site.

However, it makes for a very long and dense list though (we published 14 
titles for Fedora 13, and it looks like we might add around another 5 
titles for Fedora 14). The result was a real information overload IMHO, 
particularly with the list of titles available in the navigation pane 
immediately to the left. However, if people feel it would be useful, I'm 
more than happy to implement it.

> 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.
>    

This assumes that the user is looking for documentation for the version 
of Fedora installed on the system with which they're currently browsing 
the web. For some of our guides, that's not a bad guess. For others, 
it's considerably less likely (Release Notes, Technical Notes, 
Installation Guide).

Personally, I think we should avoid making assumptions about what users 
are looking for, and allow them to choose for themselves. However, if 
you think this would be a useful feature, this would be something else 
to raise on Publican list.

We already have the means to separate no-longer-supported documentation 
into a separate category; and I'm looking to implement that in the next 
few weeks.

> 6.) If I can't find the answer to my problems, I get directed back to
> the "Get Help" page, or to upstream documentation.
>    

A link back to the "Get Help" page would certainly be at home in the 
"Links to other parts of the Fedora Project site" and I'm quite happy to 
implement that. However, I'll wait for other responses to this thread to 
avoid making too many small changes to the page.

<big snip>

> 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.
>    

Ryan Lerch is working on a graphical front-end to Publican called 
"Endoculator" that might provide most of the workflow you're 
describing.[5] It's still under heavy development though, and is not yet 
packaged.

> 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.
>    

There is always going to be a substantial barrier with a semantically 
based approach like DocBook. This is an inherent cost of the approach 
and is readily apparent even in a friendly, WYSIWYG tool like Serna.[6]

Put another way: the real obstacle for people to contribute to DocBook 
documentation is twofold: they need to make a conceptual leap from 
presentation-based markup to semantic markup and they need to learn a 
set of semantic tags. No editor, text-based or graphical, web-based or 
locally installed, can avoid those hurdles. Beyond that comes down 
purely to personal preferences regarding workflow.

Thanks again for the extensive feedback; I hope we can translate some of 
it into concrete improvements in our delivery of content. Reading back 
over this email, I wonder if some of my replies might sound a little 
short. I hope not; in some cases, I'm just trying to triage issues in 
the direction of the teams that can fix them! :)

Cheers
Rudi

[0] http://fossdocs.files.wordpress.com/2010/03/what_is_publican.png
[1] https://www.redhat.com/mailman/listinfo/publican-list
[2] 
http://doc.fedoraproject.org/en-US/Fedora/12/html/Deployment_Guide/index.html
[3] details available at https://fedorahosted.org/deploymentguide/
[4] 
http://doc.fedoraproject.org/en-US/Fedora/13/html/Managing_Confined_Services/index.html
[5] https://fedorahosted.org/endoculator/
[6] http://www.syntext.com/products/serna-free/