Style Guide

This page will serve as a style guide for authoring this wiki and for authoring Power Automate flows. The ultimate goal of a style guide is to reduce cognitive load, and as a result, make it easier to write - text or code. How does a style guide do this? First, it reduces the number of choices you have to make as you are writing. For example, "should I write this variable name in snake case or camel case?" Second, having the predetermined choices written down for references reduces the amount of information you need to store in your intentional memory (i.e., "OK, remember to always use snake case"); although, it may eventually bleed over into your incidental memory. Third, having uniformly styled text/code makes it easier for others -- including future you -- to read. You can focus on the content instead of the style and/or organization.

TOC

• Wiki Authoring Sytle
  • Organization
  • Language
  • Emphasizing text
  • Headers
  • Images
• Flow Authoring Style
  • Naming steps
  • Naming variables
  • Comments

Wiki Authoring Style

This section contains information about syling the wiki itslef.

Organization

• Each page (.md document) should have a single, high-level theme. Over time, you may find that what you originally thought of as a theme is really more appropriate to break into multiple themes. That's OK! The goal here is to make it easy to use the wiki, and by extension, easier to use Power Automate.

• Each page should start with a brief description of the page's theme. If you aren't able to describe the theme in a sentence or two, then that may be an indication that the page doesn't have a single, high-level theme.

• Below the theme description, each page should have a table of contents (TOC). The TOC should have a bullet for every level one header at a minimum. You may choose to add additional bullets if you would like. The goal here is to make it easy to use the wiki, and by extension, easier to use Power Automate.

  • If you do, the bullets should be indented 2 spaces for every header level. For example, a level two header should be indented 2 spaces, a level three header should be indented 4 spaces, and so on.

  • Links in the TOC should be written in one of the following forms:

    • [[Page Name]]. This form will navigate to a page.

    • [Page Name](Page-Name). This form will also navigate to a page, but it allows you to alter the way you refer to the page name. For example, if I had a page file titled Page Name.md and I wanted to refer to it as My Page in the TOC, I could do so like this [My Page](Page-Name).

    • [Section Name](#section-name). This form will navigate to a section within a page.

Language

• Use informal, first person language.
• We will typically use the word "we" instead of the word "I". It's good practice for other authoring projects with multiple authors.

Emphasizing text

Use the following conventions to emphasize keywords, code snippets, and other ideas.

• Application names: Capitalize the names of applications. For example, Microsoft Outlook, Microsoft Planner, and Power Automate.

• Code: Surround code and function names with backticks. For example, utcNow().

• File paths: File paths should be surrounded with backticks.

• Folder names: Folder names should be surrounded with backticks.

• GitHub pages, planner boards, and issues: Surround all of these GitHub elements in backticks. They aren't things you would define in an index, but they need more emphasis that italics.

• Key words: Bold or italicize key words or phrases.

  • You should bold the key word or phrases if you think of it as one that you would want to define in the index if this wiki (if it had an index). For example, a step or action. You should bold the key word the first time you use it on a page. Bolding it after the first time is optional.

  • You should italicize a key word or phrase that you want to call attention to, but it is not necessarily a word or phrase that you would define in an appendix.

• Step names: In Power Automate, steps function as code Power Automate. Therefore, step names should be surrounded with backticks just like code. For example, Initialize variable.

Headers

• Each level one header should have a single, high-level theme, but not high-level enough to (currently) warrant a page. Over time, you may find that what you originally thought of as a theme is really more appropriate to break into multiple themes. That's OK! The goal here is to make it easy to use the wiki, and by extension, easier to use Power Automate.

• Each level one header should start with a brief description of its theme. If you aren't able to describe the theme in a sentence or two, then that may be an indication that the section doesn't have a single, high-level theme.

• Type two carriage returns between a level one header and the last line of text that immediately precedes the level one header. This makes it easier to find level one headers in the source markdown document. Type a single carriage return between all other headers and the last line of the text that immediately precedes it.

• Level one headers should be written in title case. All other headers should be written in sentence case.

Images

Images can be a great way to enhance the wiki. You can insert images in at least two ways.

1. You can drag and drop an image directly into the wiki in your web browser. If you use this method, GitHub will store the image on its servers and a link to the image will automatically be added to your page. That image will not be available in your local repository.

2. You can add an image to the img folder in the local repository. You can link to that image in your markdown document using the following syntax: ![File name](img/file_name.png) or <img src="img/file_name.png" alt="File name">.

Flow Authoring Style

This section contains information about authoring Power Automate flows.

Naming steps

Each block in a Microsoft Power Automate flow is called a step (see image below). However, on help pages they are often called actions for some reason. It looks like the official Microsoft documentation calls them steps, so that's what I'm going to attempt to call them as well.

When adding a step to a flow:

• Keep the step name first. For example, Initialize variable. That way, we will know what kind of step it was when we come back and view the code in the future.

• Add a brief description after the step name.

  • For variable steps (e.g., initialize and set variable steps), the description should simply be the variable name. For example, Initialize variable - linkToEmail.

  • For other steps, you may or may not want to use the variable name in the step name.

Naming variables

Use camel case. It seems to be the prevailing style in the Power Automate community.

Comments

• Use Add a note to add expression code to steps that use expressions.

• If a step doesn't use an expression, and the comment we want to make is brief, then we can also use Add a note.

• If the step does use an expression or the comment we want to make is not brief, then we will need to add a New Comment.

  • Add comments directly to actions (as opposed to adding them generally to the flow) whenever possible. Otherwise, it can be hard to figure out which action the comment is referring to.

  • Comments are a good place to put links to resources used.