Writing an Application Manual: Difference between revisions

    From KDE UserBase Wiki
    (more guidelines for sections)
    (Marked this version for translation)
    (8 intermediate revisions by 3 users not shown)
    Line 20: Line 20:
    ** Appname/Manual/Get involved #link to techbase etc
    ** Appname/Manual/Get involved #link to techbase etc


    <!--T:28-->
    If some of your sections grow too large, you can place subsections on separate pages. It might look like this:
    If some of your sections grow too large, you can place subsections on separate pages. It might look like this:


    <!--T:29-->
    * Appname/Manual # Your Contents page
    * Appname/Manual # Your Contents page
    ** Appname/Manual/An Introduction to Appname
    ** Appname/Manual/An Introduction to Appname
    Line 29: Line 31:
    *** Appname/Manual/''section 1''/''subsection 1''
    *** Appname/Manual/''section 1''/''subsection 1''
    *** Appname/Manual/''section 1''/''subsection 2''
    *** Appname/Manual/''section 1''/''subsection 2''
    and so on. You should not make sub-subsections on separate pages since that is not supported by our Docbook conversion script. In other words, avoid more than two levels below '''Manual'''.
    and so on.


    <!--T:40-->
    {{Info|The page names do not have to follow the structure of the document closely! In the above example you could simply use Appname/Manual/''subsection 2'' instead of Appname/Manual/''section 1''/''subsection 2'' and similarly for sub-subsections (as long as this procedure does not produce duplicate names {{Smiley}}).}}
    <!--T:41-->
    {{Remember|Try to keep page names short and avoid long paths. Overly long page names are cumbersome to type when you link to them, and they don't look good on the wiki pages. And always remember: The page names and their structure have no influence on the finished handbook whatsoever! It is entirely determined by the headings in the actual text.}}
    <!--T:30-->
    In order for the automatically generated Docbook to have the same contents page as the one you make on UserBase, and for links to work in the Docbook there are a couple or guidelines, that must be followed:
    In order for the automatically generated Docbook to have the same contents page as the one you make on UserBase, and for links to work in the Docbook there are a couple or guidelines, that must be followed:


    * All pages should have a heading at the very top, either a section (== ... ==) or a subsection (=== ... ===), otherwise the Docbook structure will be messed up.
    <!--T:31-->
    * The Docbook Table of Contents will list all sections and subsections regardless of whether they have a page of their own. On the other hand, subsubsections won't be listed in the Docbook TOC even though they have a page of their own.


    * The title of the section/subsection must exactly match the page name.
    <!--T:32-->
    * All pages should have a heading at the very top, either a section (== ... ==), a subsection (=== ... ===), or a subsubsection (==== ... ====), otherwise the Docbook structure will be messed up.


    * Subsection titles must be written like this: <code>==='''''title'''''===</code>, even if it is the top level on a page. Otherwise the Docbook structure will be messed up.
    <!--T:33-->
    * The title of the section/subsection must exactly match the page name, otherwise Docbook links won't work.


    * Subsections that should not appear in the contents page and should not appear on a page of its own in the Docbook must be level 4 or below, i.e ==== or more.
    <!--T:34-->
    * Subsection titles must be written like this: <code>==='''''title'''''===</code>, even if it is the top level on a page. Otherwise the Docbook structure will be messed up. Similarly, if you have a very long subsection with subsubsections on pages of their own, these pages must have their titles written like this: <code>===='''''title'''''====</code>.


    <!--T:35-->
    * Subsubsections that should not appear in the contents page and should not appear on a page of its own in the Docbook must be level 4 or below, i.e ==== or more.
    <!--T:36-->
    * Links to pages in the manual must exactly match the page name (i.e. no links via redirects!)
    * Links to pages in the manual must exactly match the page name (i.e. no links via redirects!)


    <!--T:37-->
    * If you link to a subsection of a page, you must have an anchor at the target location. Failing that will mess up Docbook links as well as translations.
    * If you link to a subsection of a page, you must have an anchor at the target location. Failing that will mess up Docbook links as well as translations.


    <!--T:38-->
    {{Note|1=Every subsection (===) gets a page of its own in the Docbook, even if it is part of a longer page on UserBase. This means that a section (==) that contain a number of subsections, but no text before the first subsection gets a Docbook page that contains nothing but links to the subsections.}}
    {{Note|1=Every subsection (===) gets a page of its own in the Docbook, even if it is part of a longer page on UserBase. This means that a section (==) that contain a number of subsections, but no text before the first subsection gets a Docbook page that contains nothing but links to the subsections.}}


    <!--T:39-->
    {{Remember|1=If at some point you decide to change the title of the main (sub)section of a page (the first headline), it is important that you also change the name of the page accordingly, and also that all links to that page are modified to match the new name.}}
    {{Remember|1=If at some point you decide to change the title of the main (sub)section of a page (the first headline), it is important that you also change the name of the page accordingly, and also that all links to that page are modified to match the new name.}}


    Line 92: Line 112:


    <!--T:16-->
    <!--T:16-->
    * Ensure that '''all''' images are in PNG format (you can use JPEG (.jpeg, not .jpg) as well, but in this case you should convert your images to PNG later).  Save work by converting them before you start [[Image:Smiley.png|16px]].
    * Ensure that '''all''' images are in PNG format (you can use JPEG as well, but in this case they should be converted to PNG by the script).  Save work by converting them before you start [[Image:Smiley.png|16px]].


    <!--T:17-->
    <!--T:17-->
    Line 121: Line 141:
    <!--T:19-->
    <!--T:19-->
    * The steps for markup editing can be found on [[Special:myLanguage/Edit Markup|Preparing a Page for Translation]].  Please adhere to that guide, since old markup styles may not still be relevant.
    * The steps for markup editing can be found on [[Special:myLanguage/Edit Markup|Preparing a Page for Translation]].  Please adhere to that guide, since old markup styles may not still be relevant.
    == Producing a DocBook manual == <!--T:42-->
    <!--T:43-->
    Once your manual is written you can have it transformed into a DocBook manual, so that your work can be used like an ordinary KDE handbook. The procedure is described in [[Special:myLanguage/How_To_Convert_a_UserBase_Manual_to_Docbook|this page]].


    <!--T:20-->
    <!--T:20-->
    [[Category:Contributing]]
    [[Category:Contributing]]
    </translate>
    </translate>

    Revision as of 09:37, 6 July 2013

    Notes

    Manuals will be included as sub-pages of the main application page. For brevity, I will refer to that main page as Appname. The structure, therefore would be something like:

    • Appname
      • Appname/Hints and Tips
    • Appname/Manual # Your Contents page
      • Appname/Manual/An Introduction to Appname
      • Appname/Manual/Configuration Choices
      • Appname/Manual/The First Time you use Appname
      • Appname/Manual/section 1
      • Appname/Manual/section xxx
      • Appname/Manual/Hints and Tips
      • Appname/Manual/Troubleshooting
      • Appname/Manual/Bug reports
      • Appname/Manual/Get involved #link to techbase etc

    If some of your sections grow too large, you can place subsections on separate pages. It might look like this:

    • Appname/Manual # Your Contents page
      • Appname/Manual/An Introduction to Appname
      • Appname/Manual/Configuration Choices
      • Appname/Manual/The First Time you use Appname
      • Appname/Manual/section 1
        • Appname/Manual/section 1/subsection 1
        • Appname/Manual/section 1/subsection 2

    and so on.

    Information

    The page names do not have to follow the structure of the document closely! In the above example you could simply use Appname/Manual/subsection 2 instead of Appname/Manual/section 1/subsection 2 and similarly for sub-subsections (as long as this procedure does not produce duplicate names ).


    Remember

    Try to keep page names short and avoid long paths. Overly long page names are cumbersome to type when you link to them, and they don't look good on the wiki pages. And always remember: The page names and their structure have no influence on the finished handbook whatsoever! It is entirely determined by the headings in the actual text.


    In order for the automatically generated Docbook to have the same contents page as the one you make on UserBase, and for links to work in the Docbook there are a couple or guidelines, that must be followed:

    • The Docbook Table of Contents will list all sections and subsections regardless of whether they have a page of their own. On the other hand, subsubsections won't be listed in the Docbook TOC even though they have a page of their own.
    • All pages should have a heading at the very top, either a section (== ... ==), a subsection (=== ... ===), or a subsubsection (==== ... ====), otherwise the Docbook structure will be messed up.
    • The title of the section/subsection must exactly match the page name, otherwise Docbook links won't work.
    • Subsection titles must be written like this: ===title===, even if it is the top level on a page. Otherwise the Docbook structure will be messed up. Similarly, if you have a very long subsection with subsubsections on pages of their own, these pages must have their titles written like this: ====title====.
    • Subsubsections that should not appear in the contents page and should not appear on a page of its own in the Docbook must be level 4 or below, i.e ==== or more.
    • Links to pages in the manual must exactly match the page name (i.e. no links via redirects!)
    • If you link to a subsection of a page, you must have an anchor at the target location. Failing that will mess up Docbook links as well as translations.

    Note

    Every subsection (===) gets a page of its own in the Docbook, even if it is part of a longer page on UserBase. This means that a section (==) that contain a number of subsections, but no text before the first subsection gets a Docbook page that contains nothing but links to the subsections.


    Remember

    If at some point you decide to change the title of the main (sub)section of a page (the first headline), it is important that you also change the name of the page accordingly, and also that all links to that page are modified to match the new name.


    Remember

    Please do not use any kind of punctuation in your page names — punctuation like question marks or periods creates serious problems for the wiki software, in particular for the translation system.


    You will need a scratchpad to experiment with section headings/pages. You can use either your UserTalk page, or the discussion pages attached to the area where you are working. It's helpful if you remove anything no longer required, once the job is completed.

    Developing a Manual

    While developing your manual it is usually best to keep it separate from the regular UserBase content. Some prefer to edit their drafts as subpages of their Talk: page. We also have a special Draft: namespace for this purpose.

    To create the content page of your manual, simply write http://userbase.kde.org/Draft:Appname/Manual in the address line of your browser, or place the [[Draft:Appname/Manual]] link in a page and then click it. Either way you will be taken to a page telling you that the page does not exist, but that you can create it clicking a link.

    Contents

    • Once you have made the decisions (that can be a lengthy procedure), create appropriate links on the Contents page. It is, of course, possible to insert a section later if you find you've missed something.

    Building your Manual

    • Use the red links to create the page, and write up a section at a time.
    • Note on the Discussion page anything you will need to refer to later, such as links that can't yet be created.

    Remember

    It's important to be consistent, particularly in Manuals, so here are some general rules:
    • Take care with heading levels - we start at second level (Mediawiki uses top level for page-name), using ==
    • Make application name formatting consistent (avoid using Amaroks, do use Amarok's).
    • Ensure that all images are in PNG format (you can use JPEG as well, but in this case they should be converted to PNG by the script). Save work by converting them before you start .
    • Remove all non-printable characters from image names.


    Searching your manual

    At some point, you may need to find something that you wrote earlier, but can't remember where. Using the wiki search box may not be ideal unless the string you search for is very specific. You can get much better control over searches using the DPL extension. For example, to find the pages in your manual containing a certain string, you can add the following to any page:

    <DPL>
      titlematch = %Appname/Manual%
      namespace = Draft
      include = *
      includematch = /string to search for/
      resultsheader = Manual Pages:
      format = ,\n* [[%PAGE%|%TITLE%]]\n,,
    </DPL>
    

    You can find more examples on using DPL on User:Claus_chr/DPL.

    Preparing the Manual for Translation

    Producing a DocBook manual

    Once your manual is written you can have it transformed into a DocBook manual, so that your work can be used like an ordinary KDE handbook. The procedure is described in this page.