📚 Documentation styling guide

This section contains information on how to document the project. This is split into 3 sections:

• General guidelines
• Customer documentation
• Developer documentation

This split is made since both of these groups have different needs and requirements when it comes to documentation. Besides that, the documentation can be found in different locations. This guide will go over both of these sections and talks about; where to find it, what information to include & how to write this information, the site structures and file designs.

Before we dive into both of the subgroups, we'll go over some general guidelines apply to both of these groups.

🚨 General guidelines

• All documentation must be written in English.
• All documentation pages are written in Markdown. Leave two blank spaces before each header to simplify reading the Markdown file in an editor.
• Use a grammar checker to ensure the text is free of spelling and grammar errors. This can be done using tools like Grammarly (online), Grazie (in IDE).
• Only write documentation that is relevant. Before writing, ask yourself: What is the purpose of this documentation? Who is going to read this? What information do they need?
• Keep pages short and to the point. Avoid long paragraphs and unnecessary information. Prefer 10 short pages over two long pages.
• Write like a human. This helps to make the documentation more engaging and easier to read. Using tools like Grammarly or Grazie can help with this.
• Prevent using tools like ChatGPT to write the documentation. This can lead to incorrect information being shared or language usage none of us would use or understand.
• Add emojis to make the documentation more engaging and easier to find the information that is being looked for. Add one to every header and use in text where applicable. Get emojis from emojipedia or Windows (win + .).
• References to Flowcontrol and Limax BV should be written as such. (not flowcontrol, Flow control, FlowControl or limax, Limax).

📖 Customer documentation

To properly communicate with our customers, we need to provide them with documentation that is straightforward to understand and follow. This documentation can be found on the Flowcontrol website.
Before we go over how this is structured and how these documentation pages should look, we'll go over some general guidelines that apply to the customer documentation.

🚨 Guidelines

• Remember the general guidelines mentioned above 😉.
• As mentioned before, write only what is relevant. Since this is intended to be read by customers, there is no need to dive into technical detail, how we develop or function as a team.
• Use clear and concise language. Avoid jargon and technical terms that the reader may not understand.
• Use images and videos/gifs to help explain features and workflows in the application. This means to include step-by-step instructions for common tasks.
• Think of yourself as a tour guide. You are guiding the user through the application, showing them how to use it effectively.
• Include troubleshooting tips and FAQs to help users solve common problems on their own. (Even outside the FAQ section).

🗂️ Site structure

The site structure of the flowcontrol home page is as follows:

homepage - homepage of flowcontrol
│
├───Navbar 
│   ├───Home (logo) - homepage of flowcontrol
│   ├───About - overal information about Flowcontrol and Limax BV and the team
│   ├───Contact - contact page
│   ├───FAQ - frequently asked questions
│   ├───Help - page with overview of flowcontrol modules and their generic functionalities
│   │   ├───Article Module - Page with information about article module and how to use it (includes feature overviews with gifs and textual guides)
│   │   │
│   │   ├───Farmer Module - Page with information about farmer module and how to use it (includes feature overviews with gifs and textual guides)
│   │   │
│   │   └───Transport Module - Page with information about transport module and how to use it (includes feature overviews with gifs and textual guides)
│   │   
│   └───Login / to dashboard - login or dashboard redirect depending on the login state
│
├───Content - main page content with some generic information and sales talk
│
└───Footer
    ├───Product
    │   ├───Change log - information about the latest releases
    │   ├───Road map - information about upcoming features and changes
    │   ├───Help - page with guides and detailed information about the usage of flowcontrol
    │   └───FAQ - frequently asked questions
    │
    ├───Company
    │   ├───About - overal information about Flowcontrol and Limax BV
    │   ├───Status - current status of the application (per module) and possible downtime 
    │   ├───Contact - contact page
    │   └───Work - information about possible possitions & internships and previous interns
    │
    └───Extra information
        ├───Map - a site map (detailing the structure of the site)
        ├───Cookies - cookie policy
        ├───Security & Privacy - information on how flowcontrol is secured & privacy policy (GDPR)
        └───Terms - terms and conditions

🎨 File design

Files for the customer documentation are written in Markdown. They should follow the following structure:

Page - some content page
│───Navbar - (see structure above)
│
├───Page title - PageHero components (holds title, subtitle and image)
│
├───Page content - 1 or multiple HomeSection components (hold title, subtitle and description of section as slots for content)
│
└───footer - (see structure above)

📖 Developer documentation

For internal communication, we can use the GitHub pages of the repository. The goal of this documentation is to document important information for us developers as well as for future developers and interns. This documentation can be found in the documentation folder of the repository.
Before we look at the site structure and file design, we'll go over some general guidelines that apply to the developer documentation.

🚨 Guidelines

• Remember the general guidelines mentioned above 😉.
• As mentioned before, write only what is relevant. Since this is for internal communication, there is no need to explain everything in detail (a basic understanding of our work can be expected), talk about upcoming features (belongs in Asana), or add unnecessary information (sales talks, etc.).
• Use diagrams to explain complex concepts. Add code blocks to show code snippets. Use tables to display data. Especially when documenting new concepts. Estimate if the team will understand the concept without the need for a diagram or code block.
• Diagrams need to be made with Plant UML and stored in the documentation directory. The diagrams are then linked in the documentation. Furthermore, the diagrams can use the extension C4.
• Assets should be placed in one of the assets folders of the documentation folder. Depending on what section the asset belongs to, it should be placed in that subfolder. Use common sense to decide if the asserts should be placed in a subfolder, e.g. documentation/site/docs/research/assets/async/ or documentation/site/docs/guidelines/assets/.
• When in doubt about; what to write, how to write it or where to write it? Communicate with your team! Together we can keep the documentation up to date, relevant and well-structured.
• Use the VitePress Markdown guide to style the documentation.
• Always link new pages to the nav and sidebars. A guide on how to can be found here.

🗂️ Site structure

The site structure of the documentation site is as follows:

homepage
│
└───Navbar
    ├───Getting started - how to install the repo and get get it running, which tools are needed, etc.
    │
    ├───Guidelines / Development
    │   ├───Code guidelines - guidelines for writing code, tests and in-code documentation
    │   ├───Architecture guidelines - guidelines for how our architecture is setup, where functionality should be placed, etc.
    │   ├───Documentation guidelines - guidelines for writing documentation
    │   ├───Asana & Agile guidelines - guidelines for working with Asana and how Agile methodology is used
    │   ├───Git guidelines - guidelines for commit messages, branching, pull requests, etc.
    │   ├───CI/CD guidelines - guidelines for how our CI/CD pipeline is setup and how it works
    │   └───Versioning - guidelines for how versioning is done in the project
    │   
    ├───Research
    │    ├───Home - explanation of the research section & links to generic reseach and articles related to Flowcontrol
    │    └───New topics and technologies - A page for each new topic or technology that is being researched to be implemented in the project
    │    
    └───Internships
        ├───Home - explanation of the internship section & links to generic information about internships
        └───Internship pages - A page for each intern's research and results

Some extra information:

• The new topics and technologies include already researched topics like security, API testing, db migrations, UUID usage, etc. and will be expanded with new topics during development.
• The internship pages are for the interns to document their research and results. This can be used for future interns to build upon and for the team to learn from and look back the research done. Add 'Internship - Name' to the navbar items.

🎨 File design

Files for the developer documentation are written in Markdown. They should follow the following structure:

Page - some documentation page
│───Navbar - (see structure above)
│
├───Page title - # header
│   └───Introduction - a short simple text introduction to the page
│
└───Sub title - ## header
    └───Page content - simple text, codeblocks, diagrams, tables, etc.
        └───Possible sub-sub title - ### header
            └───Sub-sub content - simple text, codeblocks, diagrams, tables, etc.