Foundation for the repository documentation

[elsalahy]

Summary:

We need to setup a detailed documentation pages for the GNSE and I need some input regarding how we should proceed.

[azerimaker]

We have many routes to take.

1. Create old-school PDF/User guide docs.
2. Have a dedicated device documentation page in genericnode.com website.
3. Use GitHub's Wiki or Readme files for this.
4. Create online datahseet and user guides with documentation tools like ReadTheDocs or MkDocs.

[elsalahy]

Currently we are adding some basic documentation for using the GNSE repository. In the coming days, we will need to provide a detailed set of documents around the device specifications,HW and FW development.

Looking how TTS does things in https://github.com/TheThingsIndustries/lorawan-stack-docs

We have multiple options:

1. Create a dedicated repository for the GNSE docs (exactly the same structure as TTS, but with a a new repo)
2. Use our current repo and host the docs within this repo (Same structure as TTS, just within the GNSE repo)
3. Use a GH wiki similar to https://github.com/Lora-net/LoRaMac-node/wiki
4. Use something new like https://squidfunk.github.io/mkdocs-material/

@johanstokking I really appreciate your input on this.

CC: @wienke @azerimaker

[johanstokking]

I think option (1) or (2) are best.

Regarding the four options:

1. In TTS we have a separate docs repo because we have two code repos (open source and proprietary) but one documentation site. Consider a separate docs repo if future Generic Node variants would be documented on the same site, i.e. genericnode.com/docs. That is the case, right?
2. That is fine too, but only if the docs are specific for GNSE, i.e. genericnode.com/se/docs
3. That's a poor man's solution
4. That's an alternative to Hugo and I don't see a reason to deviate from Hugo

[elsalahy]

Nice,

• I like 1 because as you mention, it will be better for expansion as we go forward for the tracking edition and including other modules/designs
• 2 is a possibility if we want to have a separation of documentation between the different devices

I prefer 1, I think I will create a template private repo and see how it looks (will inherit TTS docs style and prepare it for the the GN) and we can see if 1 or 2 is the better option as we start structuring it

[elsalahy]

@johanstokking here is a preview of what option 1 might look like.

Also here is a small preview in case you don't want to build it.

We will follow the same approach taken with the LoRaWAN stack docs and deploy to a GH pages branch.

If you feel we are on the right track, can you please create a repo for the GN documentation, maybe call it generic-node-docs

[johanstokking]

Awesome, looks great

[johanstokking]

@elsalahy repo is set up at https://github.com/TheThingsIndustries/generic-node-docs. You guys have admin access for now so you can set up branch protection, merge types, disable wiki and projects etc etc etc

[elsalahy]

Thanks @johanstokking will set it up later today and give you a heads up

[elsalahy]

The new generic-node-dcos repository is setup and we will continue documentation development and issue creation/tracking in the new repo.

Closing this issue