Update documentation

This page is out of date and needs reviewing.

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 git@gitlab.agile.coop: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/

Note that hotfix is an appropriate branch prefix if you are editing existing documentation. When creating new documentation you should use feature.

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:

feature/update-documentation-guide

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 yarn start)

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

✓ Dos

❌ Don'ts

Last updated: