Guidelines - notand/angular-tour-of-heroines GitHub Wiki
The manual roughly follows the principles of DITA writing and of technical writing in general.
Some issues proofed to be especially relevant in our context. This page lists guidelines for these issues.
Work in progress...
The manual is a task-oriented web help according to DITA [Link] standards.
Because in our context, many developers contribute to the documentation who do not all know DITA, we use a subset of DITA elements. When you contribute to the manual, do not introduce additional elements. Have a look at the XML structure of one or two existing task topics first.
If you are new to DITA, we recommend the following information sources: ... ...
- taskbody/prereq ** https://docs.oasis-open.org/dita/v1.2/os/spec/langref/prereq.html
The following guidelines are easy to understand, but it takes some conscious effort and practice to actually consistently apply them in writing.
If you are new to technical writing, we recommend the following information sources: ... ...
Linguistic guidelines:
- Use active voice
- Make clear who has done something or should do something.
- For instructions, use the imperative clause, e.g. "Open the xy.", „Öffnen Sie xy.“ ** Not: "Opening the xy." "xy öffnen."
- Do not use "Please", "Bitte", e.g. "Open the xy." "Öffnen Sie xy." ** Not: "Please open the xy." "Öffnen Sie bitte xy."
- Avoid "glue text": https://www.oxygenxml.com/dita/styleguide/webhelp-feedback/#Artefact/Language_and_Punctuation/c_Glue_Text.html
- Guidelines for topic titles
- Guidelines for paragraphs
The file names and the folder structure in the DITA project follow the following guidelines as close as possible, with a special focus on localization:
... to be continued ...
Hintergrundüberlegungen zu Grafiken in DITA: https://joepairman.com/posts/roadmap-for-adaptive-graphics
-
bevorzugte Grafikformate: svg (für Vektorgrafiken), png ** aus "DITA Style Guide":https://www.oxygenxml.com/dita/styleguide/webhelp-feedback/Artefact/Graphics_and_Figures/c_Image_File_Types.html: Unless you have specific reasons for choosing other formats, you should use SVG for line drawings and diagrams. Likewise, for photographs, use JPG with zero or low compression, particularly if you will be publishing to print formats. For other purposes, you should prefer PNG. If your publishing process does not support SVG, you may have to use PNG instead. However, a better approach is to use a publishing process which supports SVG.
-
svg und unbearbeitete Screenshots in /images/img_prep
-
alle Icons in den .svg (Ordner, File, Plugin-Symbole) sind von Esther erstellt und können daher ohne Copyright-bedenken (nach)genutzt werden
-
Standardgröße: ? (noch nicht festgelegt)
-
Markierungen mit roten (e00000) Kästen, Rahmenbreite 4px
-
-> bisher nicht geklärt wie .svg in die Doku eingebunden werden kann
-
Grundprinzipien für die Dateibenennung: ** als erstes die Softwarekomponente benennen (z.B. eXist, oxygen) ** eher Kleinbuchstaben als Großbuchstaben
Anforderungen an die Screenshots in der Doku:
- Responsivität: Anzeige des Web-Outputs in schmalem Fenster (z.B. linke Bildschirmhälfte) soll den kompletten Screenshot anzeigen, ohne zu scrollen
-
eXist-Instanz: eine saubere, nur mit den Standard-Apps. URL-Zeile wegschneiden.
-
Oxygen Author (Version 19 oder 20) mit deutschem GUI.
-
MeineEdition: Name für Projekte, Framework, etc. ** Framework: ediarum.meineEdition.framework ** Arbeitsordner: frameworks
- Aus "DITA Style Guide":https://www.oxygenxml.com/dita/styleguide/webhelp-feedback/Artefact/Graphics_and_Figures/c_Figures_or_Images.html: Although images can be placed in a DITA topic as image elements without a surrounding figure element, figures are generally the best way to structure graphics and other illustrations. The exception is for simple inline images (that is, images that are part of the flow of the text), where an independent image element should be used.
- Screenshot zu einem (In Tasks): step/info/fig/image Achtung: Falls beim Output für jeweils ein Signalwort angezeigt wird, ist das nicht ganz so ideal, aber wir machen es erstmal so. Eine Alternative wäre, (Stepexample) zu verwenden. Siehe "DITA Style Guide":https://www.oxygenxml.com/dita/styleguide/webhelp-feedback/Artefact/Syntax_and_Markup/c_Images_within_Steps.html Viel mehr Sachdienliches findet Google zu diesem Thema auf die Schnelle nicht.
If you use git as your tool for versioning and collaborative work, be aware that files are not locked during editing. Commit and merge frequently. Talk to your colleagues.