Decide on the folder structure and ToC mapping

jakubcech commented 5 years ago

Description

We need to decide on the folder structure and how it maps to the site and what is displayed on the actual site. We should expect that the folder structure contains files that we may want to exclude from ToC based on a name or a pattern. The current menu and ToC definition lives here: https://github.com/iotaledger/documentation/blob/storybook/buildList.js

If we don't want to handle 'unwanted' files, then we should only fetch files based on patterns from remote 'reference' repos. For example, the GO library docs generate reference docs for methods that we do not want to include. We only want to include specific ones. That is in my opinion not sufficient, as in API reference, we may want to list a limited subset of items in ToC and still link to objects that have files generated in the same folder, for example. The objects themselves wouldn't be listed in the ToC.

High level folder structure

(changes should be done in client libraries, where we'd like a landing page for the client libraries and then folder for each IF maintained lib + subfolders (reference and quick start)) /docs/ Introduction IRI MAM (Placeholder) Trinity Compass Client libraries

Introduction
GO
- quick start
- reference/version number/files.md
  - Java
- quick start
- reference/version number/files.md
  - JavaScript
- quick start
- reference/version number/files.md

Future folder structure

proposed by Andrew and Jake for future reference: Note: redoing the structure will mean we have to redo the links in all articles as well.

/docs/ IOTA Basics

Getting started Tangle Network
Tangle concepts
- Introduction
- Tip Selection
- Consensus in the Tangle
- Proof of work
- Compass (?)
IRI
- Introduction
- Quick start
- Knowledge base
- Networking
- Reference
MAM (Placeholder)
- Introduction
- Quick start
- Knowledge base
- Reference
Trinity wallet
- Introduction
- Quick start
- Desktop setup
- Interact
Client libraries
- Introduction
- GO
  - quick start
  - reference/version number/files.md
- Java
  - quick start
  - reference/version number/files.md
    - JavaScript
  - quick start
  - reference/version number/files.md

jakubcech commented 5 years ago

We will need to overwrite the JSON produced by https://github.com/iotaledger/documentation/blob/storybook/buildList.js to customize the ToC for client libraries - exclude the files we don't want to display in ToC + set up a structure for the API calls: core, API, and maybe bump the structure up a level as the client libs will be in docs/, but we want them under the client libraries ToC item.

obany commented 5 years ago

I have introduced a doc-index.md file which is read from each versioned folder and is used to generate the navigation

Example

# Index

[Introduction/Overview](./introduction/overview.md)
[Introduction/Use Cases](./introduction/usecases.md)

[How To Guides/Security](./how-to-guides/security.md)
[How To Guides/Hub Installation](./how-to-guides/simple-install.md)
[How To Guides/Hub plus Signing Server](./how-to-guides/signing-server.md)
[How To Guides/Create User Example](./how-to-guides/create-user.md)

[Concepts/Hub Architecture](./concepts/architecture.md)
[Concepts/Hub Functions](./concepts/components.md)
[Concepts/Exchange Use Case](./concepts/exchange-implementation.md)
[Concepts/Contribute](./concepts/contribution.md)

[References/Hub Architecture](./reference/reference.md)

iotaledger / documentation-platform