Mobile Docs

Our goal is to help users of AeroGear projects "understand things well and not feel like they’re dealing with a capricious minor god instead of a product." ^[1]

This readme introduces the standards for AeroGear docs.

Concepts, Procedures and Reference

Concept

An introduction to a new term, process, module or component. For example, "Mobile Service" : what is it? why do I care? and how does it fit into my development environment?

• Name file by slugifying title

• Prefix filenames with con_

Procedure

The important information that gets me using AeroGear software, for example, write your procedure by answering the following questions:

1. Who should perform this procedure?

2. Why am I performing this procedure? benefits or context in a higher level user story

3. What is the object of the task? eg adding a dashboard.. to what?

4. What do I need to know and/or do before installing or provisioning the software?

5. What do I need to do to provision the software?

6. What are the minimum configuration tasks that I need to do to get value from the software?

7. What additional information would be useful after completing procedure (eg, next steps)

   • Name file by slugifying title

   • no prefix on filenames

Reference

Information I might need to debug or extend the normal usage of AeroGear software. For example:

• API syntax and definitions

• Configuration optionss

• Name file by slugifying title

• Prefix filenames with ref_

Writing AeroGear Documentation

1. If you make a filename change (eg adding or renaming a file), you must update the appropriate modules/ROOT/nav.adoc file.

2. Test your changes using Antora

3. Determine which functionality is this documentation related to?

   • Push

   • Metrics

   • Common to all mobile services

   • Common to all services or SDKs but with some information that is specific to each.

     With this information, you should be able to determine where the file should be located in the repo, eg modules/ROOT/push

     If you intend to reuse a part of a file, create a partial in modules/ROOT/_partials and refer to it using an include

4. Stick to present tense, eg When you add the dashboard, it appears on …​, not When you add the dashboard, it will appear on …​

Asciidoc

For a fuller list of asciidoc syntax, see the quick reference, note the following syntax to avoid:

• Headings using --, ~~, ^^, ++ syntax

• Markdown

• Source block without syntax. Try to use syntax highlighting where possible, for example [source, bash]

Note	This page acts as example of documentation best practises: introducing terms a single procedure reference material

Modular Docs

For more information and some useful templates, see Modular Docs

Using Antora to convert asciidoc to html

After modifying documentation, you can validate your changes and preview the results by:

1. Install Antora globally as described in their install guide.

   Note	As part of Antora installation, you should install site-generator globally.

   If you encounter a libcurl error on linux, follow the Option 1 instructions at: https://docs.antora.org/antora/1.0/install/troubleshoot-nodegit/

2. Fork this repo and set up origin and upstream remotes.

3. Change to the mobile-docs directory.

4. Run antora:

   ./bin/build.sh local-site.yml

   After building for the first time, you can run the following command for subsequent builds:

   ./bin/quick-build.sh <site-file>.yml

   Note: <site-file> refers to either:

   • local-site - your current directory

   • site.yml - the master branch of the github repo

Note	After changes to antora-ui, you might need to run 'antora --pull --clean <site-file>' to pick up those changes.

Remote Repos

No remote repos were harmed in the production of this documentation ;)

However, references to code maybe be included as follows:

1. Decide on a name for the snippet, eg push-ios-register

2. Create a partial in mobile-docs, eg https://github.com/aerogear/mobile-docs/blob/master/modules/ROOT/pages/_partials/push-ios-register.inc

3. Reference the code file you want to use (with a tags filter):

    include::https://raw.githubusercontent.com/aerogear/ios-showcase-template/push-push/ios-showcase-template/push/PushHelper.swift[tags=push-ios-register]

4. Add tags to the code repo, eg

   // tag::push-ios-register[]
       public func registerUPS(_ deviceToken: Data) {
           AgsCore.logger.info("Registered for notifications with token")
   
           var config = UnifiedPushConfig()
           config.alias = "Example App"
           config.categories = ["iOS", "Example"]
   
           AgsPush.instance.register(
               deviceToken,
               config,
               success: {
                   AgsCore.logger.info("Successfully registered to Unified Push Server")
               },
               failure: { (error: Error!) in
                   AgsCore.logger.error("Failure to register for on Unified Push Server: \(error)")
               }
           )
       }
   // end::push-ios-register[]

5. Edit adoc file with the following to display the content:

    include::{partialsdir}/push-ios-register.inc-rantora.adoc[]

   Note	You need to run mobile-docs:/bin/build.sh <site>.yml to make sure the temp files are in place when building site

---

1. Laura Bailey