Escriure un manual d'aplicació
Notes
Els manuals s'inclouen com a sub-pàgines de la pàgina principal de l'aplicació. Per raons de brevetat, em referiré a la pàgina principal com Appname. L'estructura, per tant, seria com:
- 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.
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.
Necessiteu un bloc de notes per experimentar amb seccions de capçaleres/pàgines. Podeu utilitzar la vostra pàgina UserTalk, o les pàgines de debat adjuntes a l'àrea on esteu treballant. És útil si es treu res que ja no és necessari, una vegada es completa el treball.
El desenvolupament d'un manual
Durant el desenvolupament del manual normalment és millor mantenir-lo separat dels continguts d'UserBase. Alguns prefereixen editar els esborranys com subpàgines de la seva pàgina de debat. També tenim un espai de nom Draft: per a aquest propòsit.
Per crear la pàgina de contingut del manual, només cal escriure http://userbase.kde.org/Draft:Appname/Manual a la barra d'adreces del navegador, o el lloc [[Draft:Appname/Manual]] com enllaç a una pàgina i fer-hi clic. De qualsevol manera us portarà a una pàgina que indica que la pàgina no existeix, però que es pot crear fent clic en un enllaç.
Contingut
- Un vegada preses les decisions (el que pot ser un procediment llarg), creeu els enllaços corresponents a la pàgina Contingut. Per descomptat, és possible inserir una secció més endavant, si trobeu que falta alguna cosa.
La construcció del vostre manual
- Utilitzeu els enllaços de color vermell per a crear la pàgina, i escriviu una secció cada vegada.
- Tingueu present la pàgina de debat per a qualsevol cosa a la que haureu de referir-vos més tard, com ara enllaços que encara no es poden crear.
- Aneu amb compte amb els nivells de les capçaleres: Hem de començar en el segon nivell (Mediawiki utilitza el nivell superior pel nom de la pàgina), amb ==.
- Assegureu-vos que us refereiu amb freqüència a aquesta pàgina, a Tasques i eines i a Directrius tipogràfiques.
- Comproveu si totes les cel·les d'una taula tenen espai després del caràcter de canonada. Aquesta regla és conforme amb traditional wiki formatting.
- Feu que el nom de l'aplicació tingui un format consistent (eviteu l'ús de Amaroks, feu Amarok's).
- Assegureu-vos que totes les imatges estan en format PNG (es pot usar JPEG (.jpeg, no .jpg), en aquest cas és necessari convertir les imatges a PNG més endavant). Deseu el treball mitjançant la seva conversió abans de començar
.
- Elimineu tots els caràcters no imprimibles dels noms de les imatges.
Cercar al manual
En algun moment, potser haureu de trobar alguna cosa que vàreu escriure, però no podeu recordar on. Utilitzant la caixa de cerca del wiki pot no ser idoni, a menys que la cadena de cerca sigui molt específica. Podeu aconseguir un millor control sobre les cerques utilitzant l'extensió DPL. Per exemple, per trobar les pàgines del manual que continguin una determinada cadena, podeu afegir el següent a qualsevol pàgina:
<DPL> titlematch = %Appname/Manual% namespace = Draft include = * includematch = /cadena a cercar/ resultsheader = Manual Pages: format = ,\n* [[%PAGE%|%TITLE%]]\n,, </DPL>
Podeu trobar més exemples sobre l'ús de la DPL en User:Claus_chr/DPL.
Preparar el manual per a la traducció
- Els passos per a editar les marques es poden trobar a Preparar una pàgina per a la traducció. Si us plau, adheriu-vos a aquesta guia, ja que els estils de marcat antics encara no són rellevants.