Searching...

Matching results

    Writers' corner

    Welcome onboard!

    You want to write documentation for AirVantage? This is the right place to start.

    Initializing Table Of Contents...

    Introduction

    The public documentation is divided in multiple parts, 1 by product offer:

    • AirLink Management Services (alms)
    • AirLink Management Services with Connectivity (almsc)
    • AirVantage Platform (av)
    • AirVantage Platform with Connectivity (avc)
    • Connectivity
    • Unlimited FOTA (fota)

    And 1 general purpose part:

    • AirVantage User Guide (user)

    Their content is only available through the Offer user guides using a symbolic link like mecanism. The general purpose spaces are not accessible from the index page, only the product offers are.

    Workflow

    Our workflow relies on Git branches.

    We have 1 main branch, which is the master for the production documentation branch.

    Here is a graph describing our workflow:

    Here are the major things you will have to do within your branch life cycle. Examples below are using GitHub for Windows.

    Synch master branch to get latest commits

    Basically, each time you have to work on a new topic you have to create a new branch based on the master one. Each development is therefore independant of others and can be merged once ready and validated to be available in the public documentation.

    Select the master branch as the current working branch and synchronize it so that you get the latest version from repository.

    Create your branch

    Don’t forget to create your branches from the master branch.

    Make sure the master branch is the current working branch and click on the branching icon at the left to enter your branch’s name.

    Once the branch is created, click on publish so that other users can view (and therefore review) it on repository.

    Commit and push your changes

    When you’ve done significant changes, commit them to the repository and then push the changes to the external version of the repository. Committing and then pushing ensures that your changes are saved remotely and are not only on your computer.

    Committing and then pushing ensures that your changes are saved remotely and are not only on your computer.

    Create the pull request

    By creating the pull request, you’re requesting that your changes are pushed to the master branch for becoming part of the public documentation. This pull request needs a reviewer’s approval before merge into master. You have to assign one or more reviewer to look at the proposed changes.

    Merge your branch

    Once you’ve incorporated the changes requested by the reviewer, and the reviewer has approved the changes, you’ll be able to ‘Squash and Merge’. You have to specify a branch to compare to and then to merge.

    It may happen that during a merge GitHub is facing conflicts with the master branch, meaning that another branch has resulted into modifications of the same parts of the same file(s) and is not able to automate the merge and pick the right version. In that case, you’ll have to do the merge manually where GitHub was not able to resolve the conflict. Usually unresolved conflicts are mentionned using the following markers:

    <<<<<<<, ======= and >>>>>>>

    Merging the branch to master will trigger the deployment in production automatically.

    Don’t forget to delete your working branch.

    Tools

    Sublime Text 3

    This is the text editor we use to write the documentation.

    Download it from here and install it.

    Package Control

    It is the first Sublime Text add-on (package in Sublime Text terminology) to install. It’s a package installer.

    Install Package Control

    Extra packages

    Then to install new packages:

    1. Ctrl+Shift+P to invoke the Palette
      • The Palette allows you to execute Sublime Text actions by typing their name
    2. Type install to execute the Package Control: Install Package action
    3. A package search field is now presented, just enter the name of the package to install:
      • MarkdownEditing
      • SidebarEnhancements

    Snippets

    How to install snippets

    To facilitate the use of shortcodes, Sublime Text snippets are stored in the av-doc/snippets/sublimetext folder.

    To install them copy them in the Sublime Text 3 installation folder: In sublime click on Preferences -> Browse Packages... -> User

    How to use snippets

    There are two ways to use snippets:

    • In Sublime Text click on Tools -> Snippets... and choose the shortcode snippets
    • In your .md file you can type for example link, image, info … and press Tab

    Trick: If a snippet has several fields, you can use Tab to navigate between the fields to fill.

    Hugo

    We use Hugo as a static site generator. The content is written in Markdown and transformed in HTML using the various predefined layouts.

    In Hugo the content should be arranged in the same way they are intended for the rendered website. Hugo supports content nested at any level.

    You can see how your changes are rendering by launching Hugo. To do that, av-doc/content/run.bat to run Hugo and then open a browser on http://localhost:1313/ to ensure the changes you brought are looking good and as expected.

    Markdown

    Markdown basics are documented here: Markdown Basics

    Shortcodes

    Hugo uses Markdown for its simple content format. However, there’s a lot of things that Markdown doesn’t support well. To avoid writing HTML in our Markdown every time we want to include unsupported content such as a video or easily use the same layout pattern, Hugo offers the concept of Shortcodes.

    Available shortcodes documentation is available here: Shortcodes

    Front Matter

    The front matter is one of the features that gives Hugo its strength. It enables you to include the meta data of the content right with it.

    More info about it and what usage we have of it is available here: Frontmatter

    Where do I start?

    Pretty easy, all the documentation content is available in site/content.

    Let’s say you want to update the AVEP Getting Started page available at https://doc.airvantage.net/av/howto/gettingstarted. The Markdown file to edit is located at the same path starting from site/content => site/content/av/howto/gettingstarted.md.

    Images related to the markdown content you are writing need to be stored in path starting with in site/content/static/img. As much as possible, store the images in the section that is relevant for your page. For example, your page is a generic how-to from Register. Store the images in site/content/static/img/user/reference/register/how-to/.

    For the files and pictures naming, prefer the naming convention myNiceNewPicture.ext

    TOP