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

Recordeu!

Si us plau, no utilitzeu cap tipus de puntuació en els noms de la pàgina: La puntuació com signes d'interrogació o punts creen seriosos problemes al programari wiki, en particular al sistema de traducció.

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

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.

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.

Recordeu!

És important ser constant, sobretot en els manuals, així que aquí teniu algunes regles generals:

• 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.

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.

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.