Differential D6490 Diff 23575 docs/contributing/tutorial-docs-contribution.rst

Changeset View

Standalone View

docs/contributing/tutorial-docs-contribution.rst

.. _doc-contribution:		.. _doc-contribution:

Tutorial: Best practices when writing SWH docs		Tutorial: Best practices when writing SWH docs
==============================================		==============================================

.. admonition:: Intended audience		.. admonition:: Intended audience
:class: important		:class: important

Members of the Software Heritage staff and external contributors		Members of the Software Heritage staff and external contributors
who wish to contribute by writing documentation.		who wish to contribute by writing documentation.

A tutorial on how to contribute documentation into the Software Heritage world.		A tutorial on how to contribute documentation into the Software Heritage world.

Step 1: Identify your audience		Step 1: Identify your audience
------------------------------		------------------------------

#. Ask yourself: Who are the readers of the documentation that you are writing?		#. Ask yourself: Who are the readers of the documentation that you are writing?

In the Software Heritage community, three general types of personas are		In the Software Heritage community, three general types of personas are
▲ Show 20 Lines • Show All 108 Lines • ▼ Show 20 Lines	.. code-block:: rst

Empty page		Empty page
==========		==========

.. admonition:: Intended audience		.. admonition:: Intended audience
:class: important		:class: important

add the audience target(s) of this page		add the audience target(s) of this page

.. todo::		.. todo::
This page is a work in progress. For now, please refer to the `existing documentation <https://...>`_.		This page is a work in progress. For now, please refer to the `existing documentation <https://...>`_.

Empty subsection template		Empty subsection template
^^^^^^^^^^^^^^^^^^^^^^^^^		^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: rst		.. code-block:: rst

▲ Show 20 Lines • Show All 48 Lines • Show Last 20 Lines