Contribute to the documentation

We use Docusaurus to document the SemApps project. Docusaurus is used to generate documentation from Github :

  • We benefit from the collaborative environment of Github (markdown editing, versioning, commits, pull requests, reviews, etc.).
  • You can preview the changes
  • The code can be easily deployed

Where to find the Docusaurus files

How to contribute to the documentation

General scheme

  • Until there is a decision/consent from the documentation circle: Create an issue
  • If the content of what you want to publish has been approved by the documentation group :
    • Create a pull request on a dedicated branch.
    • As long as it's in draft or draft form, don't request a review.
  • When our proposal for a contribution appears to be complete, a review is requested.

Propose topics or improvements by creating an "issue"

  • Go to https://github.com/assemblee-virtuelle/semapps/issues
  • Detail your request/proposal, put links if necessary to clarify your intention as much as possible.
  • Fill in the external / internal / technical documentation label from the "Labels" tab of the menu on the right-hand side of the screen.
  • And let's discuss it!

Modify a page of Docusaurus

Go to the relevant place by referring to the previous chapter.

  • If it is a minor modification, a spelling mistake for example, make the change by editing the page (edit file), then "commit" to the Master branch. Describe your change in the space provided.
  • If it is a substantial change :
    • make the change by editing the page,
    • then "commit" to a new branch that you can explicitly name.
    • Fill in a Label and identify Reviewers who will be invited to comment / approve / propose changes to your pull request.
    • At the end of this collective process, it will be time to merger the pull request on the Master branch.

Create a new page on Docusaurus

  • Propose an issue ;

If the initiative seems relevant:

  • Create a markdown file in the desired location, remembering to fill in the extension: ".md". It must necessarily begin with :

    ---
    title: [your page title]
    ---

    NB: The page title may have spaces. On the other hand, the name of the .md file must not have spaces, and must be written in lower case.

  • Commit and make a pull request on a dedicated branch.

  • Once the reviewers you've identified have validated it, merge the pull request on the master branch.

Getting help

Our Riot/Matrix chatroom is the main entry point for all people who want to contribute.