Guidelines - notand/angular-tour-of-heroines GitHub Wiki

Guidelines

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

Information architecture

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

List of XML elements

Linguistic guidelines

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:

Files and folders

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

Screenshots/Grafiken

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

Standards für Beispielsettings und Screenshots

  • 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

Einbettung der Grafiken in die XML-Struktur

git

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.

⚠️ **GitHub.com Fallback** ⚠️