[documentation - day] Proposition (#6) · Issues · beat / docs

[documentation - day] Proposition

List of all the packages on gitlab concerning beat :

beat.tutorial
beat.examples
beat.env.python27
beat.core
beat.deploy
beat.env.web
beat.web
beat.env.develop
beat.cmdline
beat.backend.python
beat.env.backend
beat.env.docker
beat.backend.cxx
beat.env.scripts
beat.env.python
beat.env.system.python
beat.env.cxx
beat.env.client
beat.env.db.examples
beat.env.db
beat.env.rankone
beat.editor
weeklies
beat.presentation.technical
ci.env.editor
beat.tutorial.prefix
docs
beat.env.pytorch

List of packages in the aggregated documentation

beat.cmdline
beat.core
beat.backend.python
beat.web
beat.editor

From which:

beat.core documentation on beat.core components. It's a User Guide
beat.cmdline documentation on command-line client. It's a User Guide
beat.backend.python documentation on various API aspects. It's an API Guide
beat.editor documentation on how to edit beat objects. It has an Installation Guide and User Guide with an additional breakdown on how to edit each objects, and also a Development Guide, a possible API Guide for the Flask server
beat.web documentation on the platform's architecture. It has an Administrator Guide and also an API Guide and finally the platform User Guide

Miscellaneous information

The information about how to write algorithms targets what is now legacy and is not v2 compatible #5 (closed)

Proposition

Let's target "ONLY" for now the list of packages from the aggregated documentation (beat.core, beat.cmdline, beat.backend.python, beat.editor, beat.web) with an upper package beat which would pin all those packages at a specific version for a proper release.
We could imagine having a consistent track for each of these packages (I am not sure to what extend this makes sense as beat.cmdline for example doesn't have an API Guide or Development Guide):
- Installation Guide
- User Guide
- API Guide (When required)
- Administrator/Development Guide

Open questions

I was previously in favor of having a User Guide for all the packages then an API Guide for all of them again, etc. etc. but to what I see this would seem confusing. I would keep the proposition above and we should write more documentation (such as a Development Guide) for all the packages and we should spend time writing a beat.tutorial documentation which would regroup all the User Guide of beat.web, beat.cmdline and beat.editor only. Does this make sense ?

**List of all the packages on gitlab concerning beat :**

```
beat.tutorial
beat.examples
beat.env.python27
beat.core
beat.deploy
beat.env.web
beat.web
beat.env.develop
beat.cmdline
beat.backend.python
beat.env.backend
beat.env.docker
beat.backend.cxx
beat.env.scripts
beat.env.python
beat.env.system.python
beat.env.cxx
beat.env.client
beat.env.db.examples
beat.env.db
beat.env.rankone
beat.editor
weeklies
beat.presentation.technical
ci.env.editor
beat.tutorial.prefix
docs
beat.env.pytorch
```

**List of packages in the aggregated documentation**

```
beat.cmdline
beat.core
beat.backend.python
beat.web
beat.editor
```

From which:

* `beat.core` documentation on _beat.core components_. It's a `User Guide`
* `beat.cmdline` documentation on command-line client. It's a `User Guide`
* `beat.backend.python` documentation on various API aspects. It's an `API Guide`
* `beat.editor` documentation on how to edit _beat objects_. It has an `Installation Guide` and  `User Guide` with an additional breakdown on how to edit each objects, and also a  `Development Guide`, a possible `API Guide` for the Flask server
* `beat.web` documentation on the platform's architecture. It has an `Administrator Guide` and also an `API Guide` and finally the platform `User Guide`

**Miscellaneous information**

* The information about `how to write algorithms` targets what is now `legacy` and is `not v2 compatible` #5

**Proposition**

* Let's target "ONLY" for now the list of packages from the aggregated documentation (beat.core, beat.cmdline, beat.backend.python, beat.editor, beat.web) with an upper package `beat` which would pin all those packages at a specific version for a proper release.
* We could imagine having a consistent track for each of these packages (I am not sure to what extend this makes sense as beat.cmdline for example doesn't have an API Guide or Development Guide):
  * Installation Guide
  * User Guide
  * API Guide (When required)
  * Administrator/Development Guide

**Open questions**

* I was previously in favor of having a `User Guide` for all the packages then an `API Guide` for all of them again, etc. etc. but to what I see this would seem confusing. I would keep the proposition above and we should write more documentation (such as a Development Guide) for all the packages and we should spend time writing a `beat.tutorial` documentation which would regroup all the User Guide of `beat.web`,  `beat.cmdline` and `beat.editor` only. Does this make sense ?