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.
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.htm... [3] details available at https://fedorahosted.org/deploymentguide/ [4] http://doc.fedoraproject.org/en-US/Fedora/13/html/Managing_Confined_Services... [5] https://fedorahosted.org/endoculator/ [6] http://www.syntext.com/products/serna-free/
On 06/27/2010 10:01 AM, Ruediger Landmann wrote: <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.
As a question out of left field, has anyone in the docs team looked at using Confluence + Scroll Wiki Exporter?
http://www.atlassian.com/software/confluence/ http://www.scrollyourwiki.com/display/web/Scroll+Wiki+Exporter
I've used Confluence in organisations before, and it's best of breed for Wiki software. It also supports direct editing of wiki pages through OpenOffice and MS Word, which is *brilliant* for people used to using a word processor!
The Scroll Wiki Exporter plug-in for it exports the content to DocBook v5 and/or DITA, which Publican could (in theory) then build/publish. The Scroll Wiki Exporter plug-in seems to get high marks/good reviews, so thinking it might actually be a go-er.
I keep thinking I should set up an demo on a server and see if it actually works in practise, but I'm not sure if anyone is actually interested enough to have a look. :)
?
Regards and best wishes,
Justin Clift
On Sun, Jun 27, 2010 at 4:57 AM, Justin Clift justin@salasaga.org wrote:
On 06/27/2010 10:01 AM, Ruediger Landmann wrote:
<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.
As a question out of left field, has anyone in the docs team looked at using Confluence + Scroll Wiki Exporter?
http://www.atlassian.com/software/confluence/ http://www.scrollyourwiki.com/display/web/Scroll+Wiki+Exporter
I've used Confluence in organisations before, and it's best of breed for Wiki software. It also supports direct editing of wiki pages through OpenOffice and MS Word, which is *brilliant* for people used to using a word processor!
The Scroll Wiki Exporter plug-in for it exports the content to DocBook v5 and/or DITA, which Publican could (in theory) then build/publish. The Scroll Wiki Exporter plug-in seems to get high marks/good reviews, so thinking it might actually be a go-er.
I keep thinking I should set up an demo on a server and see if it actually works in practise, but I'm not sure if anyone is actually interested enough to have a look. :)
I don't believe either is open source, and thus we can't use them. (Yes, I know Atlassian will grant a free as in price license for their products to Open Source Software projects, but it's still not free as in freedom) With Freedom being one of our foundations, we make a stand that the software (and documentation) we ship, and anything that we use to ship it with is available under a free as in libre license. In addition to making it easier to follow along in our footsteps for other people who want to mirror our workflow, we think it advances the state of free software. If you saw the number of bugs filed (and fixed) by and on behalf of Docs Project team members against Publican in a single release cycle, you'd immediately see at least one reason why.