Writing a guide

Symbol Developer Documentation guides help other developers to get started on Symbol’s technology, giving step-by-step instructions on how to use the tools, integrate with other technologies, and combine the built-in features to architect solutions.

Before starting

If you are looking for inspiration to write the guide, you can browse the symbol-docs repository open issues to find some ideas pending to be written. We also encourage you to join our Slack #sig-docs channel and present yourself!

To collaborate with one of the existing issues, express it in a comment to avoid duplicated efforts. If there is no issue yet, create a new one introducing the content you want to publish.

Writing the guide

  1. Fork and clone the symbol-docs repository.

     git clone https://github.com/nemtech/symbol-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:

     .. post:: 18 Aug, 2018
    :category: <category>
    :excerpt: 1
    :nocomments:
    :author: <your_name_or_username>
#####
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 explanation.
************
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. The repository maintainers will proofread and edit the content to follow the documentation style guide.