thethingsnetwork / docs

Documentation for The Things Network

The Things Network Documentation

The documentation site for The Things Network is built with Hugo. All content is stored as Markdown files in doc/content.

Data for generated documentation like the glossary is stored in doc/data.

Development Environment Dependencies

The Things Network Documentation development tooling uses Go and Yarn.

• Follow Go's installation guide to install Go.
• Follow Yarn's installation guide to install Yarn.

In order to build the documentation site with the right theme, you need to run make deps from time to time. This will install Yarn on Mac and Unix systems if it is not already installed.

Getting Started

Install dependencies and tooling to help you comply with our git style guidelines by running

$ make init

Running a Development Server

You can start a development server with live reloading by running make or make server. This command will print the address of the server.

Building the Documentation for Github Pages

The documentation site can be built for Github Pages by running make build.public. This will output the site to public.

Building the Documentation for Internal (Offline) Use

The documentation site can be built for internal (offline) use by running make build.internal. This will output the site to internal.

Contributing

Please see the style, branch naming, and commit guidelines in CONTRIBUTING

Creating New Documentation

Run make new <path> to create a new documentation section from the template at path. For example, make new getting-started/hello will create a section in getting-started/hello.

docs's Issues

Add visuals to complex information

• OTAA activation flow
• Downlink within response window
• Bit shifting

Work with @wesselversluis on this.

Integrate with Arduino Create Agent

The OSS Arduino Create Agent is what powers the Arduino Web Editor.

It looks like we could push code directly to ones connected node from docs if the user has this helper app installed.

So far though, I run into issues even getting the web editor to work.

Rename "Dashboard" to "Console" for v2

Link to custom (sub)domain

When ready, a custom (sub)domain must be linked.

• Ideally, this site should be available on https://thethingsnetwork.org/docs
• If this is not possible it will be https://docs.thethingsnetwork.org

Merge _guides and _versions

I'd like all content to be in one root folder and content to be able to use sections and assets from other versions.

• Move _guides to _content/current
• Move _versions/refactor to _content/refactor
• Use the first level under _content as version

This does mean that URLs like /docs/uno will become /docs/current/uno. With #20 it might be possible to redirect /docs/* that lead to 404 to /docs/current/* if it exists (use site.guides to make a rule for each of them)

Add copy button to code snippets

Like Bootstrap Docs have

DX: Stay within same version when switching between guides

Currently the dropdown will always get you the current version.

Create make-your-own-guide wizard

This should:

1. Ask me what device I have to work with.
2. Ask me where I'd like to receive/process/respond messages.
3. Show me which guides to go through, e.g.
   1. Uno Quick Start
   2. Node-RED Quick Start

To enable the above all Quick Starts should use the same use case. This is already the case and since we have to assume no sensors it uses the builtin LED.

Once we have this we can extend this to:

1. Ask me what sensor I have
2. Generate a device + application QS with encoder/decoder specific to that sensor

This would be a lot harder :)

Add migration section to refactored Node.js guide

Like https://www.thethingsnetwork.org/docs/refactor/mqtt/#migration-guide

Create bootstrap-ttn module for common styles and assets

ToC can't be seen fully if there's a lot of headings

Like CLI will have:

Use same guide categories in dropdown as on frontpage

Could be done using front matter, in particular in combination with #15

Guide: Dashboard / Payload Functions

Document the ideas behind and best use of payload functions.

See https://github.com/TheThingsIndustries/dashboard/issues/77#issuecomment-248128115

Make mobile-ready

• Main navigation
• Sidebar navigation
• Responsive images and other content

Add migration section to refactored Arduino guide

Like https://www.thethingsnetwork.org/docs/refactor/mqtt/#migration-guide

Add Travis job to test Jekyll build ao

This could also check #29 and #40

Guide: Setting up Kerlink gateway

Base on https://www.thethingsnetwork.org/wiki/Hardware/Gateways/Kerlink
Markdown: https://github.com/TheThingsNetwork/wiki/blob/rewrite/Hardware/Gateways/Kerlink.md

Split up guides in multiple pages/URLs

Every guide is a one-pager now, but this makes it quite heavy and confusing to scroll through. We might want to generate a page for each section.

Do design

• Design: @wesselversluis
• Implement: @FokkeZB

Automate pulling existing content from repos

1. Generate, e.g. for TTNCTL with https://github.com/spf13/cobra/blob/master/doc/man_docs.md
2. Pull, e.g. https://github.com/TheThingsNetwork/ttn/blob/refactor/mqtt/README.md for MQTT

This should help us in particular with API reference to keep the API reference with the source but still have it available through docs as well.

It would require:

• The MD pulled in to be just that; API reference
• A script and config file with files to pull and where to put
• Run the script on every docs publish to update

Make v2-preview current once it's in public beta

Add in-page search

Like http://gettingstarted.thethingsnetwork.org/, probably using lunr.js

NOTE: Nice to have, but with a single-page guide any browser will do in-page search just fine.

Add script to check for missing/orphan assets/guides

• Scan folders for MDs/assets
• Scan MDs for links/images
• See what assets/guides are missing

Guide: Java Library

See TheThingsArchive/java-app-sdk#3

Guide: The Things Node

Add 404 page

See https://help.github.com/articles/creating-a-custom-404-page-for-your-github-pages-site/

@wesselversluis is working on a nice, clean, funny design with inline CSS and SVG so it can be used anywhere (and part of https://github.com/TheThingsNetwork/stylebook)

Move repo to thethingsnetwork

Guide: The Things Gateway

Automatically check for spelling

https://www.npmjs.com/package/markdown-spellcheck

• Use ignore file for known words
• Include in npm test

Add heading anchors

Like on http://v4-alpha.getbootstrap.com/components/utilities/

Move library documentation to their own repos

With #24 closed we should now move library documentation (at least API reference) to their repositories so they can be updated and versioned together with the actual code.

Guide: Advanced data guide

Not sure where to put this, but it should talk about:

• How scheduled downlinks work (no buffer, limited response window..)
  • A graphic would help a lot here
• Why use bytes (air time, comparison table..)
• How to encode different types of data in bytes (example functions, byte shifting..)
• How to send and decode multiple data values (name spacing..)

And maybe in the same guide also

• How OTAA and ABP work and possible issues (TheThingsArchive/ttn#234 (comment))
  • A graphic would help a lot here

Guide: Refactor CLI Quick Start

Need to update current guide for refactor API.

Add FAQ section?

Not sure if docs is the right place, but it would be great to have a searchable page with FAQs like:

• Can I register a device to multiple applications?
• ...

Lint Markdown files

To check for tabs vs spaces etc:

https://github.com/mivok/markdownlint

Rethink where to place guides, includes and assets

Images in MD don't show on GitHub or local editors because in the MD I need to do:

![]({{ site.baseurl }}/assets/image.png)

I'd like to get rid of {{ site.baseurl}} and have a relative path that works both after build and on GitHub and in editors.

Guide: The Things Network Control Utility

First discuss with Johan and Wienke if we will promote this or prefer the dashboard instead.

Update guides to use en-US spelling

• personalised > personalized

Best done after #40

Guide: Working with Bytes

Explain why (low bandwidth, limited airtime) and how to work with bytes (scale/split to 256 per byte)

Guide: Node.js

Sources:

• https://www.npmjs.com/package/ttn
• https://github.com/TheThingsNetwork/sdk/tree/master/apps/node/ttn (move to separate repo)

Prevent duplicate heading IDs

Currently if you have two identical headings (e.g. of different levels) they will get the same ID, which breaks the anchor links and TOC.

Guide: CLI Configuration section

From https://www.thethingsnetwork.org/wiki/Backend/ttnctl/Configuration, also create a refactor version. Then remove from Wiki.

Guide: The Things Uno

Base off http://gettingstarted.thethingsnetwork.org/ but pull the "The Things Network Control Utility" in from its own guide and direct to separate Node-RED guide for the last part.

Guide: Setting up MultiTech gateway

Ask Jac to move https://www.thethingsnetwork.org/labs/story/configure-your-multitech-aep-conduit-for-the-things-network and https://www.thethingsnetwork.org/labs/story/configure-your-multitech-mlinux-conduit-for-the-things-network into docs.

Guide: Node-RED

Sources:

• http://gettingstarted.thethingsnetwork.org/#retrieving-your-data
• https://github.com/TheThingsNetwork/examples/tree/master/workshops/TheThingsUno#getting-your-data
• https://github.com/TheThingsNetwork/sdk/tree/master/apps/node-RED

Rename "refactor" to "v2-preview"

Test for orphan assets

While #29 is closed, the one thing it doesn't do is check for images (and other assets) that aren't used anywhere.

Add migration section to refactored Node-RED guide

Like https://www.thethingsnetwork.org/docs/refactor/mqtt/#migration-guide

Source front-page blocks site.guides

Since guides are a collection now, any information to list them on the front page could come from their front-matter. Only challenge being grouping them.

Guide: Build your own Gateway with iC880a

Base on https://www.thethingsnetwork.org/labs/story/how-to-build-your-own-lorawan-gateway but not write too much on the casing and stuff, just on setting up iC880a