Formatting Standards¶

These formatting standards exist to keep the content of the documentation consistent.

Links¶

Link within docs using absolute links¶

When linking between pages in the documentation use the regular Markdown linking syntax, but with the absolute path to the Markdown document or area you wish to link to. For example:

... is a type of [OMAG Server](/concepts/omag-server) that ...

This ensures certain contexts in the documentation hierarchy are retained, even if deeply-nested documentation itself happens to move around, and takes advantage of the way MkDocs works to give us additional flexibility in extending the documentation later on without needing to retroactively go back and fix links everywhere that refers to that content.

Link to code with a GitHub icon¶

When linking to one of the code repositories, add both a :material-github: icon to the end of the link name, and a target to the link:

[`Foo` :material-github:](https://github.com/.../Foo.java){ target=gh }

This ensures that a reader clicking the link (Foo ) will know that they will be directed to code, and that it will open in a new tab / window.

Link to other sites with a window icon¶

When linking to some other non-Egeria site, add both a :material-dock-window: icon to the end of the link name, and a target to the link:

[some example :material-dock-window:](https://example.com){ target=example }

This ensures that a reader clicking the link will know that they will be going to some non-Egeria site, and it will open in a new tab / window.

Prefer SVG format for diagrams¶

Use regular Markdown syntax for images. For example:

![Description of what the image depicts](image-filename.svg)

To make localization easier and enhance accessibility, the preferred image format is SVG. Use draw.io for creating images and diagrams. To save, follow these steps:

1. Select everything you want to include in the diagram (e.g. Ctrl+A / Cmd+A ).
2. Use File, Export as, SVG... to save your image in SVG format.
3. Check the Selection Only box, and ensure that the Size drop-down changes to Selection Only.
4. Check the Transparent Background box.
5. Keep the Include a copy of my diagram option checked to allow later loading the SVG in draw.io.
6. If your diagram contains any embedded images (rare), be sure to check Embed Images as well.
7. Click the Export button to save the file.

The SVG format allows the diagram to be dynamically scaled in the browser without introducing various image artifacts that create noise or otherwise impair visibility of the image: making the diagrams easier to understand.

Give each diagram a unique figure number and use this number to refer to the diagram rather than using positional phrases such as "in the diagram above" which presupposes a particular layout that may not be appropriate for all devices.

Avoiding text descriptions and explanations embedded in the diagrams means that the content is also more accessible (again for screen-readers), but also more broadly in that it is then indexed by the documentation site and can be searched. (Text embedded inside a diagram or image is not searchable.) In addition, be sure to provide enough description about the diagram in the text so that if the diagram is not visible to the reader for some reason, they can still understand the message.

Providing a description of the image is required for accessibility purposes, as it will act as the alternative text for e.g. screen-readers for anyone who is unable to see the image itself. Be sure to include the figure number in the description so it can be easily associated with the text.

If your diagram depicts a process, try to avoid adding the descriptions of the steps to the diagram. Instead, only add the numbers of the steps to the diagram and add the descriptions of the steps as a numbered list in the document. Ensure that the numbers on the list match the numbers on your diagram.

Do not wrap lines¶

Avoid wrapping lines after a fixed number of characters or in a middle of a sentence. Instead, configure your editor to soft-wrap when editing documentation.

This enhances the maintainability of the documentation by a broader audience:

• different people will inevitably have different preferences for screen sizes and widths (we do not need to worry about constantly reformatting or scrolling what one or another contributor has decided is their own optimal line-break size)
• reviewing a diff of changes will be easier to identify actual content vs spacing / newline positioning changes
• changes in indentation that may be needed for e.g. bullet lists, inclusion within an admonition, etc will only require indenting the single wrapped line
• including content into a table in Markdown (which does not allow newlines within it) will be easier

Use angle brackets for placeholders in commands¶

Use angle brackets for placeholders in commands or code samples. Tell the reader what the placeholder represents. For example:

1. Display information about a pod:

   $ kubectl describe pod <pod-name>
   

   Where <pod-name> is the name of one of your pods.

Use double curly braces for placeholders in REST API urls¶

Use double curly braces for placeholders in REST API urls. Tell the reader what the placeholder represents. For example:

1. Start the server:

   POST {{baseURL}}/open-metadata/admin-services/users/{{adminUserId}}/servers/{{server}}/instance
   

   Where {{baseURL}} is the host name and port of the platform where the server is to run; {{adminUserId}} is the user id of the administrator and {{server}} is the name of the server to start.

Use bold to emphasize user interface elements¶

Use Markdown's double-asterisk to indicate bold:

Click **Fork**.

This enhances the readability of the key actions that a user is expected to take through a user interface.

Use bold to emphasize important text¶

Use bold to emphasize text that is particularly important. Avoid overusing bold as it reduces its impact and readability.

Do not use capitalization for emphasis¶

Only use the original capitalization found in the code or configuration files when referencing those values directly. Use back-ticks ` ` around the referenced value to make the connection explicit. For example, use InstanceHeader, not Instance Header or instance header.

If you are not referencing values or code directly, use normal sentence capitalization, for example, "The instance header captures key information about the metadata instance like its GUID."

For code, the back-tick form is intended to represent exactly what you're referring to, so you should specify it exactly as it is defined: with precisely the same spacing, capitalization, etc.

For non-code values, mixing capitalization makes the text harder to scan and comprehend, as well as more difficult and therefore stressful to read . Therefore, using normal sentence capitalization greatly enhances the readability of the content.

The only exceptions to this should be as follows:

• Proper nouns (i.e. Egeria)
• Any phrase that is prefixed or suffixed with Open Metadata (or an OMxx abbreviation)
• Any phrase that we commonly abbreviate using an acronym (i.e. frameworks like Open Discovery Framework): check the snippets/abbr.md for a list of such common abbreviations.

Avoid using acronyms¶

Avoid using acronyms in the text unless they are part of the name of a component or the acronym has been spelt out in full on the page along with its acronym. Acronyms are convenient short-cuts for experts but they overload novices with the need to constantly look up the meaning of the term.

Use italics to emphasize new terms¶

Use Markdown's single-asterisk to indicate italics:

Use back-ticks around file names, directories, and paths¶

Use back-ticks around inline code, commands, objects and field names¶

Only use inline code and commands to mention specific labels, flags, values, functions, objects, variables, modules, or commands.

Code blocks¶

Use the provided custom admonitions for code and configuration blocks, within which the standard Markdown triple back-tick approach can be used to give the code block itself.

Using the triple back-tick approach ensures that we can include syntax highlighting for the specific language being shown within the code block, and provides a simple single-click link mechanism for the reader to copy the entire content of that code block for further revision or pasting elsewhere.

Each admonition wraps these to give a distinct visual cue as to its content: allowing us to avoid other cues that we might otherwise need to embed within the code block itself (for example, the $ or # command-line prompts). Avoiding the inclusion of this visual cue information in the text means that readers who copy the text do not need to manually remove this from what's been copied before making use of it.

Finally, by using admonitions we not only have the visual cue but can easily make use of the distinct capabilities of the !!!, ??? and ???+ syntax to always display the content, start with the content collapsed but allow it to be expanded, or start with it expanded but allow it to be collapsed (respectively).

Use cli admonition for commands¶

Use the cli admonition to wrap the code block in a visual cue that indicates a command:

???+ cli "Brief description of command"
    ```shell
    kubectl get pods
    ```

Leave out any command-line prompt ($, #, etc).

kubectl get pods

Use post, get, put, delete admonitions for APIs¶

For APIs, use the distinct admonition that represents the type of operation: post, get, put, delete.

???+ get "GET - brief description of API call"
    ```
    {{platformURLRoot}}/open-metadata/...
    ```

While the colors have been chosen to align with the Swagger documentation colors for each operation, for accessibility purposes always start the description of the API call with the operation type.

For parameters in the URL, always do the following:

• Specify the platform URL variable at the beginning, always named {{platformURLRoot}}
• Specify the administrative user variable as {{adminUserId}}
• Specify the server's name variable as {{serverName}}
• Specify any other parameters or variables in the URL using the double-curly-brace formatting {{...}}.

This ensures that the endpoint can be quickly copied into tools like Postman, and by using the same variable names consistently someone can setup their own environment definition once and make use of all the API calls they decide to copy into the tool without needing to manually make each parameter consistent.

{{platformURLRoot}}/open-metadata/...

{{platformURLRoot}}/open-metadata/...

{{platformURLRoot}}/open-metadata/...

{{platformURLRoot}}/open-metadata/...

Use example admonition for file content¶

Use the example admonition to wrap a code block that represents a file's contents, and include both the type of content (json, etc) and the linenums="1" directives next to the opening triple back-tick. Use two spaces for indentation of lines.

???+ example "Name or brief description of file's purpose"
    ```json linenums="1"
    {
      "foo": "bar",
      "baz": {
      }
    }
    ```

This ensures that the syntax of the file is appropriately highlighted, that line numbers are printed for ease of reference, and that the indentation is not overly-intrusive (causing horizontal scrolling within the code block to become necessary).

1
2
3
4
5

{
  "foo": "bar",
  "baz": {
  }
}

Use hyphen (-) for unordered lists¶

Use a single hyphen (-) for unordered lists rather than a single asterisk (*).

This should avoid the potential for misinterpretation by the generator that a bulleted list is text that we intended (or not) to be either bolded or italicized.

Include license header¶

Every Markdown document should include a license header with the CC-BY-4.0 attribute license:

1
2

<!-- SPDX-License-Identifier: CC-BY-4.0 -->
<!-- Copyright Contributors to the Egeria project. -->

Remove license footer¶

The MkDocs generator automatically includes a footer at the bottom of every page on the site, which includes displaying overall copyright information and the CC-BY-4.0 license (and link). Therefore, these footers should be removed from the Markdown files themselves.

Include abbreviations snippet¶

A list of abbreviations is being maintained under snippets/abbr.md. This snippet should therefore be included in every Markdown document to automatically highlight and provide a hover-over expansion for acronyms. Add this line, on its own, to the end of every (non-snippet) Markdown document: --8<-- "snippets/abbr.md"

Raise an issue or comment below