Documentation guidelines

How to add a new documentation

• Create a directory in "docs/<new_subject>/ with yourmd files
• add an entry point in the configuration docs/.vitepress/<new_subject>.mts, with a new mts files (see bellow expected content)
• include this entry point in the docs/.vitepress/config.mts
  • add the inclde "import { TeamsSideBar } from "./teams.mts";
  • add the entry in sidebar

        sidebar: {
        // This sidebar gets displayed when a user
        // is on `guide` directory.
        '/products/': klaritySideBar,
        '/teams/': TeamsSideBar,
        '/artefacts/': ArtefactsSideBar,
        '/documentations/': DocumentationSideBar,
        '/<new_subject>/ : NewSubjectSidebar
      }

docs/.vitepress/<new_subject>.mts content

   export const NewSubjectSidebar = [
        {
            text: 'suject one', link: '/subject one'
        },
        {
            text: 'Todo', link: '/documentations/todo'             
        },             
        {
            text: 'Bloc 2',
            collapsed: true,
            items: [
                { text: 'Markdown Examples', link: '/documentations/markdown-examples' },
                { text: 'vitepress interna API', link: '/documentations/api-examples' }
            ]
        },
]

Documentation strategy

The Goal of this chapter is to define Safenai static documentation strategy, and so which documention shall be produce.

For each documentation item ( can be page / chapter / or part) we shall define :

• What is the goal
• Who is the target reader
• Visibility scope of documentation
  • public (accessible from our website with or without connection ?)
  • customer (All our users once connected)
  • partner (ESN which develop AI component)
  • private (limited to Safenai members)

All of this documentation item will follow a :

• A documentation Structure
• Documentation Roadmap
• Documentation lifecycle

By static documentation we mean documentation that will have one time an applicable version, shall be consult by a lot of people but do not evolve fast.

Documentation structure

Documentation structure of the documentation

Goal of documentation to be written

• Once the documentation chapter exist, move this sentance in the the created chapter

Documentation roadmap

We start by struturing evrething in this desin before split and organisation, Design will become the SafenaiSanboxConcepts for futur "quick and dirty documentation proposal".

At some point we shall plan to split this repo between, put a CD to publish the different documentation structure:

• public + customer
• partners
• private

TODO : Create issue for documentation deployment TODO : Generate a "automatic release note => list of file evolving since last release"

Documentation lifecycle

• The associated RACI edition lifecycle
  • R : Organize documentation edition
  • C : Can / shall contribute to documentation edition
  • A : Validation need version publication
  • I : Is informed of ongoing change