guidelines.asciidoc

Guidelines

• Maintain the documentation as collection of AsciiDoc pages.

• If you are using github wikis this is not the default: Always switch Edit mode to AsciiDoc when creating new wiki pages.

• For help on the syntax consult the writers guide and the quick reference.

• Start every page with the following AsciiDoc header:

  :toc: macro
  toc::[]
  :idprefix:
  :idseparator: -

• In order to make internal links work both in asciidoc pages as well as in generated documentation (PDF, ePub, HTML) you need to stick to this rules:

  • Do not use special characters (dot, ampersand, etc.) in section titles (use plain text e.g. "My Section")

  • If you link to a section, you simply use the section title in lower case with hyphens instead of spaces (e.g. "my-section"). Within the same asciidoc page you use xref (e.g. xref :my-section[link title]) and between asciidoc pages you use link (e.g. link :«pagename».asciidoc#«section-name»[«link title»]).

  • In case you want to reference the top-level section of a wiki page you need to use link without a section reference (e.g. link :«pagename».asciidoc[«link title»]) and NOT xref even if you place the link within the same asciidoc page.

  • From asciidoc pages included in the generated documentation only use link: to other asciidoc pages that will also be part of the generated documentation. Otherwise you would produce dead links.

• For editing larger files and offline work we recommend to clone the asciidoc documentation with git and use an AsciiDoc editor tool.

• You need to ensure that the files use UTF-8 as encoding.

• To include images you need to follow this rules:

  • The best choice for high quality rendering is SVG. As the wiki does not create mimetypes you have to put the image on the github pages.

  • You have to set the size so it gets properly rendered in the PDF. The width value to make it fit properly on the PDF page is 450:

    .Image Title
    image::http://devonfw.github.io/devon4j/images/«MyImage».«format»["alt-text", width="450", link="http://devonfw.github.io/devon4j/images/«MyImage».«format»"]

• For devonfw the asciidoc pages belong to categories that are also reflected by a naming convention:

  • coding-* is used for pages about general aspects to development and writing code.

  • guide-* is used for pages that act as a guide to a specific topic. It describes what to do and how to do it for that topic from the perspective of a developer.

  • alternative-* is used for pages that are not part of the suggested standard but are commonly used or popular alternatives to a proposed standard solution. Such page explains how to use such an alternative solution.

  • architecture is reserved for the architecture documentation.

  • introduction-* is used for pages that are part of the introduction into the documentation (motivation and general goals).

  • devonfw-* is used for pages that are about the devonfw itself and will not be part of the official documentation.

  • tutorial-* is used for pages that are part of the tutorials.