When browsing the documentation, each page has an "Edit this page" link at the bottom. Clicking this link should take you directly to GitHub's web editor, which will allow you to edit and preview your changes, as well as commit them for review.
The documentation files are written using Markdown, which is a text format that supports simple formatted content (for example, bolded text is written between double asterisks **like this**). You can read more about markdown features here.
To create a new documentation page, create a new .md (or .mdx if you'd like to use React features) file under the docs/docs/ folder. By default, the name of the file will be the name of the page, and placing subfolders will automatically create collapsible sections in the sidebar. If you'd like to change the default name, URL, or position in the sidebar, you can add front matter to the file with additional metadata.
If you are adding a new folder, a _category.json file can be included to change how the folder appears; see here for more info.
When editing a page, consider that the main audience of the documentation are new users of Bitsy who may not be familiar with all the terminology in Bitsy or of its more advanced features. A general guideline for the tone is 'informative but approachable'.
The 'Tools' section of the documentation is split up according to the individual tools in Bitsy. Further sub-pages are used when a tool requires a change of tab or has especially complex features.
Each tool has a general description, followed by an annotated diagram of all the features. Feature annotations should be numbered in the images, rather than text labels, to allow for localisation.
Images for the documentation were originally created in Miro. For an introduction to using Miro please visit https://academy.miro.com/learn/course/getting-started-with-miro/getting-started/what-is-miro?page=1 . If you would like to edit or add more images you can access the board at https://bit.ly/3Bz6ptN. You can duplicate any diagram to edit a new version, or unlock / lock diagrams to edit the originals.
Once you have an updated image that is ready to go, screenshot it and save it in the .images folder of the tool it belongs to in docs/docs/.
Once you've made a change, you'll need to put up a pull request (PR) in order for others to be able to see, review, merge, and eventually release it.
If you are using the "edit page" link from inside the docs UI, you will be prompted to create a PR right from the GitHub UI. See GitHub's official documentation for info on a few different ways you can create a PR.
Once your PR is submitted, a few things will happen automatically:
- Reviewers will be assigned: One of them will need to approve your changes before they can be merged
- The change will be tested for errors (at the time of writing, these tests are very basic, so make sure to also test manually!)
- A temporary build with your changes will be created and uploaded, which can be useful for testing. To get a download link from your PR:
- Select
Show all checks- this will expand to show you the automated actions - Select
Details- this will take you to a page with more information about the build job - Select
Summary- this will take you to a page with information about the automation run - Under
Artifacts, select the link with your branch name - this will download an archive with the build result - Extract and run this build on your local machine as needed
- Select
All reviewers are volunteers working in their free time, so please give us a few weeks to get to your PR. If no one has started reviewing your PR after a month, you can leave a comment on the PR and add the help wanted label to indicate it needs attention. If no one is available we'll try to give an estimate of when we expect to someone to have time to review your change.
Once a review has started, the reviewer will review your change for accuracy, style (see the style guide above), and length. Do your best to make changes requested by the reviewer, however, it is ok to politely push back if you disagree with them. The reviewer will do their best to respond in a timely manner to comments and revisions once they begin the review process. If for any reason a review must be paused or a change rejected the reviewer will explain why and update the status of the review so you aren't left hanging.
Thanks for contributing to Bitsy's documentation!
If you want to test your changes locally before submitting a PR, see the README in the docs folder for instructions. Note that this requires a bit more technical knowledge, but will allow you to interactively see changes in the browser as you edit files.
To translate documentation, a specific file structure is used: The original English documentation is placed in the folder docs/docs/, and translated documentation is placed under the folder docs/i18n/[locale]/docusaurus-plugin-content-docs/current/, where [locale] is the two-letter code for the translated language.
For example, if you wanted to translate the glossary from English to French:
- Find the original file:
docs/docs/glossary.md - Find the locale code:
fr - Create the new file:
docs/i18n/fr/docusaurus-plugin-content-docs/current/glossary.md - Translate the contents of the original file into the new file.
Note that all files in the documentation folder (including images and .json files) can be translated by putting a copy in the corresponding locale folder.
This section is a stub. You can improve the docs by expanding it.
The editor localisation file is available at https://github.com/le-doux/bitsy/blob/main/dev/resources/localization.tsv