Writing Documentation

You can improve MyPaint by making instructions for people using and people making it. Good documentation is vital for everyone. Any sort of improvement, including fixing typos and improving readability, is greatly appreciated.

Want to help improve our documentation but don’t know where to start? Our issue tracker contains issues with the documentation.

Blogs & User Guides

This is the meat and bones of the project’s documentation efforts. Ensuring users have a solid understanding of the MyPaint application’s functionality through user guides, and new versions through release notes is vital to a healthy version lifecycle.

Tone and Writing Style

• Page titles and headings should be in title case.
• Write using language understandable by a 12 to 14 year old.
• The MyPaint project has contributors across the world, and doesn’t prescribe the use of any one dialect. As long as it’s clearly understood by most English readers, your preferred dialect of English is okay to use.
• Do not assume readers’ level of technical or artistic skill.
  • Avoid using “just” or “simply” when giving instructions.

Translation

If a page is complete, please consider translating it into other languages. MyPaint’s design documentation aims to be a single source of truth, so decidedlly not translating it reduces overhead.

Hugo’s page on multilingual content

Please also consider translating MyPaint (the program).

Developer Documentation

As a MyPaint developer, you are entrusted to keep the project’s developer documentation up-to-date. Poor or missing documentation is an obstacle to new contributors, and you can help combat this by writing documentation. If you are new to technical writing, here are some resources to get you started:

• MDN Web Docs’ blog post
• Google’s courses
• FreeCodeCamp’s articles

Backend

Backend docs exist for two reasons:

1. To act as a primer given to new developers so that they can get started as quickly as possible. They’re presented to the reader as:
   1. Here’s a file/concept.
   2. This is the gist of what you need to know.
   3. You’re now prepared to read through the code and understand the specifics.
2. To help scope files/directories by describing them.

The most detailed documentation for the project will always be contained within source code.

UX/UI

GUI changes are drafted in the docs, and then applied per those specifications in the program.

Using Software

Hugo

This section details how to create and modify pages for this website. The MyPaint website is created using Hugo, a static site generator. Pages are written in Markdown (here’s a guide).

Quick start (Desktop):

• At the left side of this page, there’s an aside menu with a “Page Information” heading.
• Under the Page Information heading, there is a link to the source markdown file for this page. Click it.
• Start getting your bearings by comparing what you see on the source file to what you see on this page.

Conventions to follow when creating or modifying pages:

• Break lines before the word that starts after the 80th column
• Pages have summaries generated from page content or front matter. They may be created:
  1. Automatically at the 70th word
  2. At the position of the <!--more--> tag in the content.
  3. In front matter, using the summary key.
  • Try to avoid the first case here and instead use case 2 or 3.

Other

• Main page image: Page bundles may include a file named index.jpg or index.png, preferrably accompanied with the imgAlt front matter. Such image files will:
  • Render the image behind the page title.
  • Add meta image tags (for e.g. OpenGraph)

Front Matter

Front matter is used to store a page’s metadata. Refer to this page. to learn how to use front matter. This site’s front matter is written in TOML.

List Pages

Shortcodes

Shortcodes extend markdown with custom HTML templates. Refer to this page to learn how to use shortcodes.

Useful Hugo Builtin Shortcodes

Custom Shortcodes

Python

Docstrings

We seem to be settling on Sphinx’s autodoc syntax for writing docstrings. Where it doesn’t contradict, please follow PEP 257 too.

Python code should always have docstrings describing what a public function or class does. We would like to use Sphinx’s autodoc to generate API documentation one day, but conventions have not yet been settled for it. For now, please document parameters using Sphinx-style info field lists, and try not to use too much additional ReStructuredText markup.

class Example (_ExampleBase):
    """Demonstrative example class."""

    def add_two(self, n1, n2):
        """Adds two numbers, or other objects.

        :param object n1: The first object to addify.
        :param object n2: The second object to addulate.
        :returns: The summified results of the two arguments.

        Any kind of object can be added provided it's supported
        by the builtin "+" operator. You might as well use that.

        """
        return n1 + n2

When it’s not obvious what a bit of code is doing, add comments to explain why you are doing something.