How to write and publish a tech note

A Tech Note is an Ayla Docs page focused on a technical topic of current interest to at least one prospect, customer, or partner. Tech Notes are published on the Tech Notes page. Any Ayla employee can write a Tech Note.

Workflow

  1. The author initiates the process of writing and publishing a Tech Note by creating a Jira Ticket with a summary composed of the phrase "Tech Note:" plus the proposed topic. (e.g. "Tech Note: Ack-enabled properties").
  2. The Ayla Docs team creates a Github directory like this one for the Tech Note. The directory contains an index.md file like this one.
  3. The Ayla Docs team links from the Jira ticket to the Github directory, and notifies the author via email.
  4. The author opens the Jira ticket and clicks on the Github link.
  5. The author opens the index.md file, clicks the pencil icon, and starts writing the Tech Note, saving periodically by clicking the Proposed changes button at the bottom of the page, asking the Ayla Docs team questions via the Jira ticket, and uploading any relevant images to the Github directory.
  6. The author solicits peer reviews by emailing the index.md link to reviewers who provide feedback (1) in the Jira ticket or (2) in the index.md file using the following syntax:
     [Joe]: # (This is my inline comment.)
    
  7. The author finishes writing the Tech Note, deletes all inline comments, and notifies the Ayla Docs team via the Jira ticket.
  8. The Ayla Docs team edits the Tech Note, communicating with the author as necessary via the Jira Ticket.
  9. The Ayla Docs team publishes the Tech Note by generating an Ayla Docs page, and adding a link to the Tech Notes page.

The writing process

General

Here are guidelines for writing a good Tech Note:

  1. Understand your topic.
  2. Understand what your audience needs to know about your topic, and include only that.
  3. Write concise, accurate content.
  4. Avoid vague adjectives like fast, incredible, and easy.
  5. Minimize text decorations such as italics, bold, quotation marks, and underlines.
  6. Start by writing a few paragraphs, and then requesting a quick review from the Ayla Docs team.

Metadata

Tech Note metadata appears at the top of the index.md file like this:

title layout author createDate lastModifiedDate
Handling ack-enabled properties technote.html Matt Hagen May 31, 2020 June 1, 2020
  • title: Use sentence case.
  • layout: Enter technote.html.
  • author: Enter your name.
  • createDate: The Ayla Docs team will enter this date.
  • lastModifedData: The Ayla Docs team will enter this date.

Headings

  1. Use sentence case.
  2. If necessary, use Level 3 headings (### Level 3) to group content. In many cases, this will suffice.
  3. If necessary, use Level 2 headings (## Level 2) to group Level 3 headings and content. This will produce a Page TOC.
  4. If necessary, use Level 1 headings (# Level 1) to group Level 2 headings and content. This will also produce a Page TOC.

Images

If you plan to include images with your Tech Note, always discuss your ideas with the Ayla Docs team via the Jira ticket, first. This will save you time. Issues related to images include the following:

  1. Does the image add value to the Tech Note?
  2. Will the image become obsolete quickly?
  3. Does the image contain PPI?
  4. Does the image contain extraneous or distracting information?
  5. If a diagram, is there a more effective way to diagram the information?

Images on Ayla Docs include shadows rather than borders. The Ayla Docs team can help you achieve this effect.

To add an image to your Tech Note, do the following:

  1. Upload the image file to your Tech Note Github directory (in the same directory with your index.md file).
  2. Use an <img> tag to include the image in your Tech Note. Always set width and height (using an Aspect Ratio Calculator as needed). Max width is 800px.

Here is the markdown version:

<img src="img-600.png" width="300" height="180">

Here is the html version:

Lists

Use a numbered list to provide steps. Each step should start with a verb, or a prepositional phrase and then a verb:

  1. Browse to this website.
  2. Click on this button.
  3. In the IP Address field, enter the IP address.

It is possible to include code snippets and images in lists. Below is an example. Code snippets and images must be indented with four spaces. An image must be wrapped in a <div> tag.

Here is the markdown version:

1. At vero eos et accusamus et iusto ...
    ```
    $(function() {
      $("select.ayla-regions").change(function() {
        writeRegionUrls()
        displayAccounts()
      })
    })
    ```
    Temporibus autem quibusdam et ...
    <div><img src="img-600.png" width="300" height="180"></div>
1. Excepteur sint occaecat cupidatat ...
1. Lorem ipsum dolor sit amet ...

Here is the html version:

  1. At vero eos et accusamus et iusto ...
     $(function() {
       $("select.ayla-regions").change(function() {
         writeRegionUrls()
         displayAccounts()
       })
     })
    
    Temporibus autem quibusdam et ...
  2. Excepteur sint occaecat cupidatat ...
  3. Lorem ipsum dolor sit amet ...

References