From Fedora Project Wiki

Revision as of 08:54, 29 July 2010 by Rlandmann (talk | contribs)

This page is a draft only
It is still under construction and content may change. Do not rely on the information on this page.

The term guide here refers to any piece of formal Fedora documentation maintained by the Fedora Documentation Project and published on http://docs.fedoraproject.org. Guides range from detailed manuals hundreds of pages long to short articles that describe specific tasks such as how to burn a DVD from an ISO file.

Your guide might be an entirely new piece of writing or a project that you are migrating to Fedora from elsewhere, for example, a Red Hat Enterprise Linux document that you are bringing upstream into Fedora. These instructions apply in either case.

Prerequisites

Before you follow this procedure, you must

Apply to have your document hosted on fedorahosted.org

  1. Visit the Fedora Infrastructure Trac at https://fedorahosted.org/fedora-infrastructure/
  2. Click the Login link near the top right of the screen and supply your FAS username and password when prompted.
  3. Click the New Ticket link near the top right of the screen.
  4. Fill in the Short Summary with:
    Hosting request for NAME_OF_YOUR_GUIDE
  5. Select Hosting Request in the Type drop-down menu.


File a ticket to request hosting from the Fedora Infrastructure team: https://hosted.fedoraproject.org/fedora-infrastructure/newticket

Fill in the fields as follows:

  • Short Summary: Hosting request for name_of_your_guide
  • Type: task
  • Priority: minor
  • Component: Hosted Projects

Use the following template for the full description of the ticket:

Project name: myProject

Project short summary: myProject does X and Y, for the purpose of Z.

SCM choice (git/bzr/hg/svn): git

Project admin Fedora Account System account name: myAccountName

Yes/No, would you like a Trac instance for your project?: no

Do you need a mailing list? If so, comma-separate a list of what you'd like them to be called. Otherwise, put "no": myProject-developers

Send commits to the following list (leave empty if none needed): list-name@lists.fedorahosted.org


You can find instructions for filling out the ticket here: https://fedorahosted.org/web/new

Note also:

   * Git is the preferred SCM for Fedora Documentation
   * By convention, documentation Git repos are prefaced with docs/, so request docs/Your_Guide.git as the Project Name in the ticket.
   * It's a good idea to recommend a Trac instance so that you can publish some basic details of your project. For example: https://fedorahosted.org/install-guide/

Add your guide to the Docs Project guides table

When you have some hosting space and have checked in your source code, add your details and details of your guide to the guides table in the Fedora wiki: https://fedoraproject.org/wiki/Docs_Project_guides_table#Guides

Add your guide to Transifex

Transifex is the Fedora Project's translation interface.

If you have a stable version of your guide, create a separate branch in which translators can work. This branch is named after the branch of Fedora for which the documentation is to be released. The master branch of your document is used only for developing the English text and should not contain POT or PO files. The process for branching a Fedora document for translation is outlined on the Fedora wiki: https://fedoraproject.org/wiki/Branching_a_document_in_git

The translation branch should contain the Publican pot directory and any language directories that you are importing. You should also run publican update_po to add a few other languages heavily translated in Fedora, including nl-NL (Dutch), pl-PL (Polish), pt-PT (Portuguese), sv-SE (Swedish), and uk-UA (Ukrainian).

When you have created the translation branch, follow the instructions on the Fedora wiki to request the Fedora Localization Team to add it to Transifex: https://fedoraproject.org/wiki/L10N/FAQ#How_do_I_add_a_module_to_Transifex.3F_.28.23add-transifex.29

If your guide is still under development, you do not need to create a branch for translations yet. Wait until you finalise the English content first.

Publish your guide on docs.fedoraproject.org

Check out the git repo that holds the content of the docs.fedoraproject.org website:

ssh://USERNAME@git.fedorahosted.org/git/docs/web.git

Build your book in Publican, then insert it into a logical place in the directory structure. Edit the top-level index.html file to link to your book in the formats and languages in which it is available.

This process is currently (May 2010) undergoing changes to accommodate the new web publishing features coming in Publican 2.0.