docs June 2010

docs@lists.fedoraproject.org

35 participants
63 discussions

default link for untranslated books
by Domingo Becker 03 Jul '10

03 Jul '10

I was looking for the F13 install guide at the new docs site [1] but, as there is no Spanish version yet, the site seems to indicate that there is no install-guide at all [2]. Is it possible to have at the left the links to the English version for the untranslated books? So the Fedora documetation list is complete. New users will see untranslated guides in English and would probably want to join us in the translation efforts. What do other language coordinators think? [1] http://docs.fedoraproject.org/ [2] http://docs.fedoraproject.org/es-ES/index.html kind regards Domingo Becker

7 9

Fedora 14 Schedule
by John Poelstra 02 Jul '10

02 Jul '10

I've completed what a Fedora 14 schedule based on the same spacing and dependencies in Fedora 13. Grouped by release: http://poelstra.fedorapeople.org/schedules/f-14/f-14-docs-tree-tasks.html Pure chronological: http://poelstra.fedorapeople.org/schedules/f-14/f-14-docs-tasks.html Please let me know of any changes or adjustments you would like me to make. John

2 2

Guide Versioning
by Eric Christensen 30 Jun '10

30 Jun '10

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 So at what point does a guide go from F12 to F13 to F14? Is a mid-cycle released guide the current version (F13) or is it draft if the guide isn't complete but is relevant to the current release? -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.14 (GNU/Linux) Comment: Using GnuPG with Fedora - http://enigmail.mozdev.org/ iQIcBAEBAgAGBQJMIsTFAAoJEDbiLlqcYamxlFMQALFq9aT+4cdQwo6LdBDNq74a QrSRQ/5b4reXSNmMdq5zxaQ6UQ6xKVNbvOhh98u/7+YiRTSg9plmcuIZrquJf3kH wjeZ5SrygdVoEy+94RTi6x3BKXsMrSt6oYMKWt4TetXWbmo5Emb6L8TQWFlwy9e4 OXaGmjBDsHoW0+acDn80xHfzLZgLWoGF33UaJPHY0UFGj8m4yymXUn+iuyukZjzU eSg4RR7GwUrwcoS3CVkWDGc9W6AxhqLPK5YpNVUk8w+mwOiNYuEbX617gKViLjty kUr7IOQI5NGFRy+U2bOYyblkACVr1dEXaD9Qx2bIb5Zluo9M7gcPnxZCJ4CM3Suj 6+k5o6v0p7wUwBoEgT2o5CyopSiZc09MJwBNzmn0UhCPsJP7/2b9lktcEI9ADTGq VyXI7eNOS4cr2HvOgZv+UO+Y5+MiidMddaozHE+Vk+UM51DKhRv+8GbBbm/fCwah 3Ympsdri5EbnlSH1idEB2NMr/6z9yXf7/mDbtG5BSp4wBJU4IQHRBKmq+ewbYKSe 5ikdXSi2DWAPsCxP51ov2GtJNUj4KmRolqNGetTdtzprU32T/K7HB9tiFYIspwnA gour5/BqgA3PF4nCrywIDn0Lzaa42V78GOsjiJLWwzgUFd6yY7kXbHztKSOiPZOi 8qPTRVaWGgVLGLePzENw =xD1H -----END PGP SIGNATURE-----

5 12

Fedora Docs Meeting Reminder
by Eric Christensen 30 Jun '10

30 Jun '10

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 REMINDER: There will be a Fedora Docs Meeting today at 2300 UTC. The agenda can be found at: http://fedoraproject.org/wiki/Docs_Project_meetings#Agenda_for_Next_Meeting -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.14 (GNU/Linux) Comment: Using GnuPG with Fedora - http://enigmail.mozdev.org/ iQIcBAEBAgAGBQJMK2eYAAoJEDbiLlqcYamxyIkP/358hFz+JbVvLlzCL4Cjsf4J jz6/QbEIRGAJFg7wzRQLVtxQIqZCpz22NGzFkFSZzOCm3T0nJ9vmEK+OlD/ss7Nq Kxh0/eEWQqUSXoW2g6zHG1iT31T4hmCql8oBIpcQ8BVkYfjBLvChP9ap97RPh3cu xuRliS2M6hTEqh+5ocoShfKv3+nrlx0JHSXCSSAbIIvtY+zekLgb5dXp3PNI0SLr EBDTArbw3cts0AyrA2gRpGsM1pD/fk0G/xvGiEaw73q+1PuQ1V+q8Cjgel3Lmyne Em2ixHDrUhrxmjRgmiV1Z+KBD2OWD2Dep9QqUJHb7E1KFW6ujlivFOoq8XmJ+EEa gK2BeB0NATy0VfVych4rVTYpNotMu3lK65l4agiFgt3YeD/79FBC1Bux/EVqIykj iiIxKp7XjZ1yK/rMq8OQbyfp7LCiwaarnKT4PhYE2Qac66NiZ97R/mEcXK9a7qUY SjDOaUHa7TyAQZUBebyQ/sswyXgYDUICc75r2kFmp1P+wodrRE+8++hG8VsF9DWa Z5FcDte6nYM8qglZNTfiKRAaHgVpCe8xhEjZAJItPrlg+/E5mB0SE9u0e03huNa5 C/oTCA2Yd9XQxoE3T0FVFJ5trRvabmFspR0M1ZoKnngKztIMdcavRKqyvEeuEn/9 fKtLrkvQRNBAfL4xLT+O =YoVv -----END PGP SIGNATURE-----

1 0

Fedora 14 Schedule Tasks
by John Poelstra 28 Jun '10

28 Jun '10

Start End Name Wed 26-May Tue 19-Oct Create POT files for All Guides

1 0

Docs CMS Idea
by Christopher Antila 27 Jun '10

27 Jun '10

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: >1. 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: >2. 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.

4 3

Docs CMS ideas
by Karsten Wade 25 Jun '10

25 Jun '10

While I've been waiting to see how the Zikula deployment went with Fedora Insight, we've finally seen a better update to docs.fedoraproject.org by using the native Publican site building tools. I've waited to push forward with a CMS solution for Fedora Docs until we had a working solution to design against. 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. 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. Talking in the meeting yesterday, I threw out some ideas around this and agreed to bring those here. I'm still interested in helping drive a CMS-like project for Docs. So I'll throw out a proposal to get us started. This proposal exists partially because of our commitment to using Publican to publish. Another option is to use Publican only to generate documents, which are then loaded and versioned in a CMS e.g. Zikula or Drupal. Working under this other option would be more like the CMS experience others have -- you either work in the native editor, or you upload documents you created elsewhere. == Docs CMS == === Terms === * Publican is a command-line toolchain for building books as HTML, PDF, Epub, Text, etc. and publishing them to a static website with a navigation sidebar. It uses books written in DocBook XML that exist as installable RPM packages. * Beacon is a wysiwyg, webUI editor that has been extended to support DocBook XML editing. * Fedora Hosted (fh.o) is a hosting solution that is the source repository for Fedora Docs. Books primarily use Subversion or git as source control manager (SCM). * WebUI is a generic term for the web user interface that we have to write or configure to wrap around and perform certain functions for this CMS. For example, it can present a button to a person with publishing privileges, when pressed triggers of a Publican build on the backend. This webUI could be custom code written in Python and TurboGears, or it could be Drupal with a few custom modules. * A reader has the ability to read the website anonymously. No credentials are required. * A writer belongs to a 'doc-writers' group and also belong to the group associated with each document, e.g. 'gitinstall-guide'. Being in the 'doc-writers' group is a prerequisite that exposes the Beacon editor function. * An editor is the same as a writer, performing a different role in the process. * A publisher is a member of the 'doc-publishers' group, which gives the permission to trigger special functions in the webUI - build a doc, rebuild a doc, install a doc package, etc. === WebUI architecture === Functions: 0. Read 1. Write/edit 2. Publish 0. Read a. Publican produces pages and navigation at docs.fp.org. i. These pages are static and not wrapped by the webUI. b. Readers use Publican's navigation to read guides. 1. Write/edit a. Writer clicks "Check out document for editing" (this is NOT a locking mechanism.) i. Clicking check out triggers a 'git clone' of the document repo. ii. The cloned git repo is then branched locally to the webUI server, for example 'git branch quaid-20100224-UUID' with a short, sequential UUID such as 'AA00'. iii. Beacon is then opened using the local file check out of the XML. iv. Beacon saves work only in the files in the cloned repo. An added functionality could trigger 'git commit' on save, but this might cause too many commits without a log message. v. The writer's training includes knowing to commit on a regular basis, in a granular fashion, when one or more edit+saves makes a good bundle for a commit. Clicking on "Commit changes" opens a log summary window, then a 'git commit -m "$dump_from_log_summary_window" is done on the local repo. vi. A writer's session should persist. When the writer returns and still has local changes committed but not pushed to the master git repo, the writer is offered those files to continue work on, or to checkout a different document. vii. When the writer is done with the writing session, the writer clicks a "Check in document to main repository". This triggers a 'git push' to the master repository. 2. Publish a. Publisher selects a document and version from a dropdown/checklist menu. i. This list is generated from installed packages on docs.fp.o, information extracted using 'rpm' commands. b. Publisher clicks "Rebuild and publish document." i. A koji scratchbuild is triggered, which grabs the latest source from the upstream repository and builds a package. ii. When the build is done, the package is installed from koji using yum. c. Publisher adds a new document to the publish list. i. Document must exist as package in koji already. ii. Publisher uses a Moksha widget to identify the meta-package OR a specific package name and version are supplied manually. iii. Package is installed on docs.fedoraproject.org. iv. Cached list of installed packages is refreshed to update document and version dropdown/checklist menus. <eof> - Karsten -- name: Karsten 'quaid' Wade, Sr. Community Gardener team: Red Hat Community Architecture uri: http://TheOpenSourceWay.org/wiki gpg: AD0E0C41

3 2

I have changed my account.
by giannhs.var＠thegworld.gr 24 Jun '10

24 Jun '10

I have created a new account at FAS2 and applied again in the Docs Commit Group.My new username is gsvarsa, all the other info is the same.

2 7

Docs Project meeting summary for 23 June 2010
by Eric Christensen 24 Jun '10

24 Jun '10

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Minutes: http://meetbot.fedoraproject.org/fedora-meeting/2010-06-23/fedora_docs.2010… Minutes (text): http://meetbot.fedoraproject.org/fedora-meeting/2010-06-23/fedora_docs.2010… Log: http://meetbot.fedoraproject.org/fedora-meeting/2010-06-23/fedora_docs.2010… -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.14 (GNU/Linux) Comment: Using GnuPG with Fedora - http://enigmail.mozdev.org/ iQIcBAEBAgAGBQJMIqKoAAoJEDbiLlqcYamxDWkP/2okwSM8KHb8Yduzr1Pm0z26 f1za/KX1qs2SJGtf/uBEBw6A1R79GdJ7DC5DlbyiddUeBZh2w+FZdxPIxAZvdjHT T29aURgBb7K26n6xldzP+GMbgnZ+awlfNwqmKy8IzCV4idpOusn/KztvsW3za3IC UPOeXj8a4Gn/zBubDkQDA4X8bVBH0fTDJ0SxB6uxyqmZ7l/O7CeY+7xSJaMbYfYB Ax/zgfCVIMLPjfOqD+0OdKuJGPj/T+rpXfkmLxCA91tQyy/MPv7Ucyt9HmjTJFLK R2y4fTEyFu2kkc9SO2d737bnAH3nFanAE5bTpQ0uPOQWun2jYwkpxQiVUPYUL6K7 uxfqSKGBBPHBNk/r/cpCE/QxBolCa9xE+ni1nUkw9ePaXnmnpq6rl3tksU1oniNI FjtQ7MQi0ddjLypKTFzpIw8ERtvwPG4XPlq4UIvhrOz0Q+u71ZdIrMAXvGi8KRQK U7OX7rBpnsmLkYdjdgtenbfAU3iKCJTFNMCEcGgEVE8/IjR2qT0dgHaXUYEIPegP oIttQsQxlEF8DUUpZ4JBJRAGG/oJ+wYEsJldGx+6i9PRD47flsoij2z2NxzI6S8F yfDO/98Dj+XFhVt/8ERMBVXVZU+yrKt/TJIJ2IV/YqEJTxkzebIfbDJhWah93nmF z29qlWY9HgEmTMQkUpPF =pPMq -----END PGP SIGNATURE-----

1 0

Fedora Docs Meeting Reminder
by Eric Christensen 23 Jun '10

23 Jun '10

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 REMINDER: There will be a Fedora Docs Meeting today at 2300 UTC. The agenda can be found at: http://fedoraproject.org/wiki/Docs_Project_meetings#Agenda_for_Next_Meeting -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.14 (GNU/Linux) Comment: Using GnuPG with Fedora - http://enigmail.mozdev.org/ iQIcBAEBAgAGBQJMIfyIAAoJEDbiLlqcYamxVZ0P/2pSN2MjnHJ1WC8nNPJbBAGr 39Dz2w+jymYf53W5oxGelrnzSoCEwtA8Sb1iaonhxbPSCJwXywsPj+SHP3kXyrmZ pdn1Eb8+pCVKRY2OQKRbyG8zk4BU/EA2We8wAOBt/y6wVNK/hqNZ0d4tcItIJ+Rn yoVVp1LE+OAjBzrBmUD+jRKExra0keRKv97zVhiruY/U3kIplYBrMNUE+Omt1VEd U7Y3yq9inHIKvjJ09VzSPHilh092L1CtW4vO4ZToiZ62aPfptGDYaAzwIicogiM8 vHlZq8LAle6LaX8T6AR2fDEQdVKiCYJuuReg8zIqRzPbR2dNJtrynPi6OODeZHQA RxyJrOcpn6g7uUY5CKEg6jh41mggTIFFLVGiKOYZ9DgleVNt1SgvV5fvVkGmKq7a 1bdgDKC3QDvOxasoRQ9YDQXfSMdt4N1YHF9bjD+c6ZM3zrKUyedm0L41UQnCc8ty 3zNZ9AfwklZi90IXEPl1DsIe1DG18f0ZFifxqmt7mwSoZvIChl8a2kJ0LptZwirG pTMsgzVS2uqTD9dMFFv0BLP1yT2BQL6fS7epKz+Bg19ogxLYXeU4Fz138FfcSg8V MfMUxhyorOW946b/3yQsHJttZP/OMOSqJWAxQVSa80TPmQup3VN0b6Eh4phg2pJ2 jdQ/Eo/4q7PJm624Am8s =qhu3 -----END PGP SIGNATURE-----

1 0

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

2007

2006

2005

2004

2003

2002

docs June 2010