Documentation
Reading, writing, and maintaining documentation is an important part of any project. This section will help you get started with the documentation for MindSpaces. The documentation is written in Markdown and is located in the docs directory. The documentation is built using Docusaurus, which is a static site generator. The documentation is built and deployed to GitHub Pages.
Layout
If you feel like your page doesn't fit into any of these categories, you can always create a new category. However, it is recommended that you try to fit your page into one of the existing categories first. If you do feel like you need to create a new category, please ask first.
The documentation is organized into several sections, there are three top level categories: Research, Design and Development. Outside of these categories there are also a few top level documentation pages: Introduction, Getting Started and the Glossary. When adding a new page, it should be added to one of these categories.
So, what category should you add your page to? The categories are meant to be broad and general. If you are unsure which category to add your page to, you can always ask. However, a good rule of thumb is the following examples:
Research: This category is suitable for pages that cover research activities related to MindSpaces. It includes things like market research, audience research, and technology research. Use this category if your page is focused on exploring a problem, identifying user needs, or investigating new technologies.
Design: This category is suitable for pages that cover the design aspect of MindSpaces. It includes things like user experience design, software design, and graphic design. Use this category if your page is focused on the visual and interactive aspects of the project, and how users will interact with the software. This category is also used for designing the software architecture.
Development: This category is suitable for pages that cover the development aspect of the software project. It includes things like software architecture, programming, testing, and deployment. Use this category if your page is focused on the technical details of building and deploying the software.
Contributing
To ensure that our documentation remains clear, consistent, and helpful, we ask that all pages be written in English. However, if you would like to contribute to translations in other languages, please reach out as translations are always welcome.
To contribute to the documentation, please follow these guidelines:
Choose the appropriate category: When adding a new page or updating an existing one, please make sure to choose the appropriate category based on the content of the page. This will help keep the documentation organized and easy to navigate.
Use consistent formatting: Please use consistent formatting throughout the documentation. This includes headings, lists, and code blocks. If you are unsure of how to format something, please refer to existing pages for guidance.
Use clear and concise language: Please use clear and concise language throughout the documentation. Avoid jargon or technical terms that may be unfamiliar to readers. If terms are used that may be unfamiliar to readers, please add them to the Glossary and link to it from the page.
Provide examples where appropriate: When discussing technical concepts or features, it can be helpful to provide examples to illustrate your points. Please provide examples where appropriate to help readers understand the content.
Check your work: Before submitting your changes, please double-check your work to make sure it is accurate and free of errors. This will help ensure that our documentation remains helpful and reliable.
Thank you for your contributions to our documentation!
If you have any questions or need further guidance, please don't hesitate to reach out.