Skip to main content

Introduction

Purpose​

This documentation serves as a centralized repository of technical knowledge and guidelines related to our department's projects. It aims to provide a clear and comprehensive understanding of our tech stack, coding standards, and operational procedures to both existing and new team members.

Contributing​

We encourage every member of the department to contribute to this documentation. Here's how you can do it:

1. Fork the apps repository​

git clone git@github.com:OmnipresentGroup/apps.git

2. Follow the instructions to run the app locally​

The pre-requisites described in the README, will allow you to run the documentation locally.

yarn start docs

3. Create a new branch and make your changes​

Update the documentation, following the Markdown Guidelines and the Docusaurus Guides.

Simple doc page​

Create a markdown file under the apps/docs/docs/<folder_name>, where the folder name represents the targetted section in the sidebar.

Blog post​

Create a markdown file under apps/docs/blog and start the filename with the current date.

Resource​

The list of links that appear under the Resources dropdown, are managed in the apps/docs/docusaurus.config.js file under themeConfig>navbar>items.

4. Submit the changes​

Once a pull request is created, you can check the outcome on the dev environment: https://docs.dev.omnipresent.com.

Note: The search functionality is only available on built apps, and therefore not locally.

Tips on writing documentation​

Clarity​

  • Write in a clear, concise, and straightforward manner.
  • Use headings and subheadings to organize content.

Consistency​

  • Follow a consistent style and formatting.
  • Use the same terminology throughout the documentation.

Examples​

  • Use diagrams, flowcharts, and other visual aids to help explain complex concepts and workflows.
  • Ensure examples are correct and easy to follow.

Review​

  • Have others review your documentation for accuracy and clarity.

Maintenance​

  • Keep the documentation up-to-date with the latest information and best practices.

Support​

If you need help or have any questions, please reach out to the Frontend team on the #frontend Slack channel or consult the Docusaurus documentation.