Skrivevejledning til applikationsbogen

Denne side handler om hvordan vi gerne ser at man skriver i applikationsbogen. Hvis du vil vide hvad vi gerne ser skrevet om, så kig på vores todo liste.

Det tekniske først: Bogen er skrevet i SGML – du kan læse bogen "Linux – friheden til at skrive dokumentation" om hvordan det rent teknisk fungerer. Den kan du finde på http://www.linuxbog.dk/.

Generelt

Bogens målgruppe er personer der er relativt nye indenfor Linux, og ikke har 10 års erfaring med at finde programmer til Unix, søge på freshmeat, rpmfind.net, får KDE eller Gnome digest, osv. Programmer der løser 99% af en opgave og er nemme at bruge/gå til, er gode programmer at beskrive, fremfor programmer der løser 110% af en opgave, men kræver memorering af 18 kommandolinie options, en dyb forståelse af syntaksen i perl, regulære udtryk og asynkron montering af NFS filsystemer. Der skal også være plads til den sidste slags programmer, men hvis der mangler en "programtype", så start med at skrive om den første slags.

Vi ser gerne bogen skrevet i "vi" form – ordet "jeg" er bandlyst. Til gengæld skriver vi til vores læser som "du" – og forsøger at undgå brugen af ordet "man".

Mads har en personlig kæphest i tankestreger. En tankestreg ser sådan her ud – og kan ikke skrives på nogen anden måde. Det er et ord, efterfulgt af et mellemrum, efterfulgt af koden "ogtegn""ndash""semicolon" efterfulgt af et mellemrum, og så et nyt ord.

Forsøg at begrænse antallet af referencer til Windows. Brug den fulde form: "Microsoft Windows" hvis Windows skal omtales. Skriv gerne noget ala "I modsætning til andre operativsystemer, som f.eks. Microsoft Windows, eller Macintosh OS X" osv.

Henvisninger til URL'er skrives i ulink tagget. For den tekst der står i bogen (altså imellem ulink åben og ulink luk) skrives ikke http://, men ellers skrives linket. Der afsluttes ikke med / hvis det sidste ikke er en fil. For selve url'en skrives http:// og der afsluttes med / hvis ikke der linkes til en fil. Eksempler (i html) www.linuxbog.dk og www.linuxbog/index.html. Man kan også vælge at skrive nogen andet end et link, hvis man synes det er mere passende.... (input ønskes).

Skrivning om "emner"

Nogen gange vil det du skriver, være et nyt selvstændigt "emne", f.eks. "Instant message programmer". I sådanne tilfælde er det en god ide at indlede med et par afsnit der fortæller hvad der i det hele taget er tale om. Det er også en god ide at henvise til et par meget overordnede hjemmesider om emnet, enten i starten af emnet, eller som afslutning.

Når du skriver om programmer

Det kan være meget forvirrende hvordan man skal skrive et programnavn. Hvis programmets forfattere bruger en speciel kapitulering, anvendes den, f.eks. gThumb og GQview. Hvis ikke, anvendes stort begyndelsesbogstav, f.eks. jhead -> Jhead. Undtaget herfra er programmer der bruger gtk, eller er til Gnome, der begynder med g og har et efterfølgende logisk navn. gthumb -> gThumb, gexif -> gExif. Når man skriver om selve en kommandos navn, skrives den som den gøres på systemet i command tags: <command>gthumb</command>. (Kommentarer til navngivningen er meget velkomne...)

Når du skriver om programmet, så kan du bruge nedenstående spørgsmål som inspiration – forsøg at give et svar på så mange af dem som du kan og finder relevant (i naturligt sprog, ikke på listeform).

TODO: Skal der være noget om at vi vil have en dato for hvornår programmet er omtalt?

Det er helt OK at henvise til programmer uden at bruge ret meget fra ovenstående liste, f.eks. "programmet xyz fra www.xyz.org kan også anvendes til at lave gnyffer med". Saml gerne henvisninger sidst i et afsnit om det samme emne; Hvis du har skrevet om 4 forskellige programmer til at lave websider i, så afslut gerne med et afsnit med henvisninger til yderligere et par stykker, istedet for at sprede henvisningerne rundt i hovedafsnittet.

Forsøg i videst muligt omfang at bruge indexeringstags om programmer, så de enkelte programmer kan slås op i index. Til dette bruges SGML indexterm konstruktionen.

Omtale af programmer skal ledsages af en angivelse af hvordan man får fat i det pågældende program, typisk programmets hjemmeside. Hvis programmet er del af de "store" distributioner, så skriv at "programmet typisk følger med din distribution, men ellers er hjemmesiden for programmet http://www.example.org/foo", hvor du angiver programmets hjemmeside i et sgml ulink tag.

For programmer der er kommercielle/har en ufri licens, skal dette altid angives.

Programmer der ikke længere vedligeholdes er vi ikke så glade for at medtage i bogen.

Om installation af programmer

Bogen indeholder i indledningen nogen generelle instruktioner i installation. Henvis til disse i det omfang det er nødvendigt. Hvis programmet kræver en meget speciel installationsprocedure, så forsøg at beskrive denne så præcist som muligt, men uden at skrive side op og side ned om dette.

Forsøg at redegøre for om programmet kræver nogen specielle biblioteker. Skriv gerne om disse typisk følger med distributioner.

Screenshots/skærmskud

Screenshots (som skal skrives som "skærmskud" i bogen) af programmer er gode. Vi foretrækker at skærmskud tages enten under Gnome, eller under KDE med en så standard style/theme som muligt. Vi har intet imod andre Windows managere/skrivebordsmiljøer, men af hensyn til et nogenlunde konsistent udseende, foretrækker vi at begrænse det grafiske udtryk.

Størrelsen af et skærmskud afhænger af hvad du ønsker at vise. Sørg for at eventuelle detaljer er synlige. Pas på med at have for mange vinduer på eet billede (f.eks. et program med 17 åbne dialogbokse). En god bredde er mellem 900 og 1000 pixels – med en passende højde. Hvis du tager et skærmskud af en dialogboks, så brug en størrelse der er naturlig for denne dialogboks. Forsøg at undgå høje/smalle eller lav/bredde vinduer.

Husk, selvom et billede siger mere end 1000 ord, vil vi alligevel gerne have at der er nogen tekst om programmet – læseren skal vide hvorfor du synes at programmet fortjente et skærmskud.

Denne side vedligeholdes af Mads Bondo Dydensborg (<madsdyd@challenge.dk>)