[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 ?