Skip to content

Code Style

Code style is important in any project that is based on source code and no less so in a documentation project.

  1. Indent using spaces (ASCII code 32) not tabs.
  2. Multi-level bulleted and numbered lists must be indented using four spaces for each subsequent level.
  3. Wrap long lines of text using a line length of 78 characters.
  4. URLs that appear on a line may continue beyond the 78 character limit without a line break
  5. Use the "hash" character ('#', ASCII 35) to introduce text headings and include a line break after each heading.
  6. Use two spaces at the end of a line to force a line break in the text.
  7. Links to external documents must not be included directly in articles. Instead, add the external document link and title to /docs/rear-matter/references.md. Use an note reference to an external document in the referencing article. See instructions for noting references below.
  8. A reference to another article in the text should be noted using a superscript that acts as a link to the corresponding article. The text of the superscript should be the group-qualified article number. This can be accomplished with the following syntax:
    consolidate logs using a platform provided log manager.<sup>[Q8](../Q/008-logging-and-monitoring)</sup>
    This renders as: consolidate logs using a platform provided log manager.Q8
    As shown in this example, the link URL should generally be a relative URL to the article in question and it must not include the .md extension.
  9. An external reference in the text should be noted using a superscript that acts as link to the list of References in the document's rear matter. The text of the superscript should be the number assigned to the reference. This can be accomplished with the following syntax:
    The _AWS Well-Architected framework_<sup>[1](/rear-matter/references)</sup> is an excellent source of such practices.
    This renders as: The AWS Well-Architected framework1 is an excellent source of such practices.