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/ -- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/docs
