Writing a guide

Before starting

If you are looking for inspiration to write the guide, you can browse the bitxor-docs repository open issues to find some ideas pending to be written. We also encourage you to join the Discord server and introduce yourself in the #docs-general channel!

To start working on one of the existing issues, state your intention in a comment to avoid duplicated efforts. If there is no issue yet, create a new one (See Making suggestions) and then start working on it.

Writing the guide

1. Fork and clone the bitxor-docs repository.

   git clone https://github.com/bitxorcorp/bitxor-docs.git
   

2. Make sure you have Python 3.4+ and pip installed.

   python --version
   

3. Install requirements using pip:

   pip install -r requirements.txt
   

4. Create a new rst file inside one of the guides folder.

   mkdir source/guides/<folder_name>/<title>.rst
   

5. Write and code your guide in restructuredText. If you need help to format your text, you can check this cheatsheet.

   You can use the following template to organize your content:

   #####
   Title
   #####
   
   The objective to achieve after finishing the guide.
   
   ********
   Use case
   ********
   
   Explain the necessary concepts before starting to code.
   
   *************
   Prerequisites
   *************
   
   - A
   - B
   - C
   
   **********************
   Getting into some code
   **********************
   
   Present the code and step-by-step explanations.
   
   ************
   What's next?
   ************
   
   Is there any extra exercise that readers could try on their own?
   

6. Add the code examples under source/resources/examples/<language_or_tool>. You can render fragments of code from a file inside your .rst file with the directive example-code.

   .. example-code::
   
      .. viewsource:: <relative_url>.ts
          :language: typescript
          :start-after:  /* start block 01*/
          :end-before: /* end block 01 */
   

7. Test and preview your changes.

   make livehtml
   

8. Push your changes and create a pull-request.

   Don’t worry if you don’t get everything right on the first try. The repository maintainers will proofread and edit the content to follow the documentation style guide.

For more information about the bitxor-docs repository continue reading the Documentation guide.