How to create or update this documentation
We use the open source Docusaurus application to compile our documentation. Docusaurus uses straight forward Markdown files making documenting relatively easy for anyone.
You can either set up locally and edit or create documentation (option 1, preferred) or to make quick changes you can do it directly on Github (option 2).
Option 1: Set up developer docs locally
You will most likely want to write and test your documentation locally and we have wrapped Docusaurus in Lando making it much easier to set up.
First clone the repository:
git clone email@example.com:docs/dev.git devdocs
Change directory to your newly cloned repo and bring the lando container up:
cd devdocs; lando start
Once the build process has installed the node modules you can change into the website directory and run the server:
cd website; lando yarn start
You will then be able to view the compiled documentation locally at http://devdocs.lndo.site
Create a new branch locally, using something like this command:
git checkout -b hotfix/
hotfix is an appropriate branch prefix if you are editing existing documentation. When creating new documentation
you should use
Make your changes to the Markdown files you want to edit.
Commit your changes and open a Gitlab Merge Request against master for review by the team (notify someone to review it).
Option 2: Edit the documentation directly on gitlab
In this repository locate the file you want to edit.
Click on the edit icon which will show an editor window titled "Edit file" where you can edit and preview the markdown.
Make your changes and when satisfied write a suitable commit message, then edit the
Target Branch field to look something like:
When you edit the Target Branch field a checkbox will appear allowing you to start a new merge request. You should ensure this checkbox is ticked.
Once you commit changes a merge request will be issued and you should ask another member of Agile Collective to review your changes. Once approved they will be merged with master and deployed automatically.
Writing new documentation
You will need to create a new Markdown file in the appropriate directory with the file extension
.md. This file needs a 'header', have a look at the others to see the format.
When you want to preview it you can visit your local site http://devdocs.lndo.site at the correct url (depends on your file name and location).
If you want your file to appear in the sidebar for easier navigation you can edit
/website/sidebars.json and add an appropriate line. Your file will only appear in the sidebar if you restart yarn (Control + c then
Updates to the live documentation
When you commit to the
master branch and push it to origin you will trigger a build in the CI server which compiles the site and updates the static files, hosted at http://dev.docs.agile.coop. You can view any issues within the gitlab projects 'CI/CD' tab for 'dev'.
Important notes for writers
- Do regularly review the content here
- Document workflows and standard processes
- Don't mention specific clients in these docs
- Don't write about specific server configurations or directories that could potentially be a security issue