Formatting conventions

Tekton documentation uses Markdown to format the content. See theMarkdown cheatsheet to gain a basic understanding of Markdown conventions.

Lists

The key point of lists is that they present information in quickly scannable form, and to accomplish that they must be homogeneous. If the items in the list do not look and read the same, the reader will stumble on them. Follow these guidelines:

• Keep the length and language of your list items as homogeneous as possible. If, for example, most of your list items are single words or short fragments, try to rewrite the outliers to read like the rest.

• Capitalize the first word of each item.

• Punctuate the ends of all items in the list as follows:

  • If your list items are single words or short fragments without verbs, do not put a period at the end of each item.

  • If most of your list items are complete sentences or fragments that contain verbs, put a period at the end of each item.

See the Google Developer Style Guide entry on formatting lists for more detail.

User interface elements

• Use bold to indicate anything that’s clickable, such as buttons or menu items.

  Do	Don't
  Start your build by clicking Build.	Click on the build button to start your build.

• Use the exact label given to the UI element, screen, or page.

  Do	Don't
  Choose your Smurfs by clicking Select Smurfs.	Click select to choose your Smurfs.

• Use “quotes” to denote the name of a non-clickable elements, such as a menu or a page.

  Do	Don't
  Click Next to advance to the "Set Up Billing" page.	Click Next to open the billing setup page.

Commands and code

• Format these as code and indicate what they are:

  • API objects
  • Commands
  • Names of files and directories

  For example:

  Do	Don't
  Define a new TaskRun instance.	Define a new taskrun.
  Run the smurfcaptor command.	Run smurfcaptor.

• Use angle brackets for placeholders, such as variables, and tell the reader what the placeholders represent. For example:

  To force-catch a specific Smurf, run the following command:

  smurfcaptor -f <target-smurf>
  

  where <target-smurf> is the Smurf you want Smurfcaptor to catch.

  When the operation completes, Smurfcaptor displays the result.

• Use informative variable names and format them using camelCase. For example:

  Do	Don't
  targetSmurf	tarsmu

• Remove trailing spaces. Some markdown objects, such as lists, require a specific number of spaces, and often, the absence of spaces in specific places, in order to render properly on the website. They can also cause unnecessary lint errors.

Links

• Never use “here” or “this” as a link anchor. Use either the exact title of the document being linked, or descriptive, in-context phrase and a brief description of the link target. This enables more meaningful results when searching the documentation set, and is more informative to the reader. For example:

  Do	Don't
  For more information, see Installing Smurfcaptor.	For more information, go here.
  See the Tekton website for tutorials that cover Smurfcaptor integration.	Go to this site for tutorials.