machinery-tool

Styleguide for Machinery Documentation

This guide provides answers to writing and style questions commonly arising when editing the documentation. The following rules are intentionally kept concise. Refer to our SUSE Styleguide for more information.

Audience

Our main audience for the documentation are system administrators. Adjust tone, style, and technicality of the text based on the intended audience.

Physical Structure

The documentation is written in Markdown and contains:

• a "main" file machinery_main_general.1.md which consists of an overview of the machinery command, its global options and a brief description of all subcommands, and

• its subcommands, stored in separate files each named machinery-SUBCOMMAND.1.md.

• Scopes are described in the documentation attribute in plugins/SCOPENAME/SCOPENAME.yml

Tip: To create a file for your subcommand, copy an existing one to machinery-SUBCOMMAND.1.md and edit the latter according to the following "Logical Structure".

Logical Structure

The structure of each subcommand contains:

• the title

  Use the following format:

    ## SUBCOMMAND—Short Description
  

• a section "Synopsis"

  Contains the output of machinery SUBCOMMAND --help or machinery help SUBCOMMAND. Use square brackets for options which are optional.

• a section "Description"

  Summarize the purpose of the subcommand in a short, first paragraph. Leave an empty line, and then describe what the command does, what its output is, and which interaction may be needed.

• a section "Options"

  List all options. Use a separate list item for each option and wrap short and long option name in back ticks. State if the option is mandatory or optional as in this example:

   * `-n`, `--name=NAME` (optional):
     Save system description under the specified name
  

  Capitalize any placeholders.

• a section "Prerequisites"

  List all the necessary topics, items, or other conditions that the user have to be fulfilled beforehand the subcommand can be executed.

• a section "Dependencies"

  List only those dependencies which cannot be expressed as package dependencies. Package dependencies are automatically resolved when the machinery package is installed.

• a section "Examples"

  Provide at least two meaningful examples of how to use the subcommand. Start with the most common or easy one and explain what it does. Include also a more unusual or difficult example. Use the following style:

    * Short description:
  
      machinery SUBCOMMAND --opt1 ...
  

Level of Detail

The Machinery documentation is mainly a reference: an overview of Machinery itself, its subcommands, and usage examples.

Keep the documentation concise. Avoid describing implementing details. Focus on what the user can do with a subcommand, what information it gathers, and its results.

For example, it is unimportant whether a subcommand uses rpm, zypper, or anything else to retrieve a package list. In that case, it is enough to mention that Machinery gets this list somehow and focus on what it does with this information.

Language

For language and spelling rules, refer to our SUSE Styleguide, section "Language" which covers most of your questions already.

If you are unsure about spelling, go to the Merriam Webster homepage or consult our SUSE Terminology.

Consistency Hints

• Be consistent. For example, if you explain the --name option and start your description with a verb, do so for the other options as well.

• Distinguish between the Machinery project (with capital 'M', without any markup) and the command line tool machinery (lower case, written with back ticks and displayed in a monospace font). Always be clear in your text what you are referring to.

• Use back ticks for the machinery command, its subcommands, options, and placeholders:

  `machinery`
  

• Write in full sentences, even in lists.

• Capitalize placeholders, for example, machinery show NAME.