README

#######
Docness
#######

Vision, tips and conventions about documentation content and workflows.


**********
Ressources
**********

* online documentation: http://docness.readthedocs.org/
* code repository: https://github.com/benoitbryon/docness
* bugtracker: https://github.com/benoitbryon/docness/issues


******
Status
******

**This is a proposal.**

Although applied on private or small projects, this documentation howto should
be considered as a proposal. It is not industry standard and have not been
supported by some "big" projects.

However, **give it a try!** and `give feedback`_.


******
Vision
******

Context
=======

In software development, when developers contribute to projects, they read and
write documentation. Most people agree documentation matters.
But everybody has its own culture, habits and vision about documentation.
Thus it appears quite difficult to share vision about documentation and
then create efficient documentation.

Goal
====

.. code-block:: gherkin

  Feature: shared vision and best practices about documentation

    In order to share vision about documentation and create efficient
    documentation material
    As member of a development team
    I want to share best practices about documentation.

    Scenario: Adopt documentation-related vision and practices
      Given a project
      And a team
      When the team documents the project
      Then team members follow guidelines provided at
      http://docness.readthedocs.org/
      And reference it in the project's documentation.

Scope
=====

This project mainly deals with documentation you write within a dedicated tool,
i.e. not docstrings (documentation within code).

Related work
============

Best practices and vision are not enough. We need productivity tools:

* Coding standards. Here is a `style guide for Sphinx-based documentations`_.
* Templates, snippets and content generators. Here are `templates for
  Sphinx-based documentations`_.


*****
Usage
*****

* Read and follow `documentation best practices`_.
* Reference it in your own's project's documentation.


**********
Contribute
**********

Create tickets
==============

Please use the `bugtracker`_ **before** starting some work:

* check if the bug or feature request has already been filed. It may have been
  answered too!
* else create a new ticket.
* if you plan to contribute, tell us, but don't wait for us! So that we are
  given an opportunity to discuss, join forces or give feedback as soon as
  possible.

Fork and branch
===============

* Work in forks and branches.
* Prefix your branch with the ticket ID corresponding to the issue. As an
  example, if you are working on ticket #23 which is about headings convention,
  name your branch like ``23-headings``.

Download and install
====================

System requirements:

* `Python`_ version 2.6 or 2.7.
  
  .. note::

    The provided Makefile uses ``python`` command. So you may use
    `Virtualenv`_ to make sure the active ``python`` is the adequate one.

* Access to the Internet.

Execute:

.. code-block:: sh

   git clone git@github.com/benoitbryon/docness.git
   cd docness/
   make install

If you cannot execute the Makefile, read it and adapt the few commands it
contains in the ``install`` section to your needs.

Hack
====

They said "Eat your own dog food", so follow:

* `style guide for Sphinx-based documentations`_
* `documentation best practices`_

In your commit messages, reference the ticket with some ``refs #TICKET-ID``
syntax.

Test and build
==============

Build the documentation and review your work before commit.

.. code-block:: sh

  make build-documentation

Share
=====

* Push your code
* Submit a pull request


**********
References
**********

.. target-notes::

.. _`code repository`: https://github.com/benoitbryon/docness
.. _`bugtracker`: https://github.com/benoitbryon/docness/issues
.. _`online documentation`: http://docness.readthedocs.org/
.. _`give feedback`: https://github.com/benoitbryon/docness/issues
.. _`style guide for Sphinx-based documentations`:
   https://github.com/benoitbryon/documentation-style-guide-sphinx
.. _`templates for Sphinx-based documentations`:
   https://github.com/benoitbryon/documentation-templates-sphinx
.. _`Python`: http://python.org
.. _`Virtualenv`: http://virtualenv.org
.. _`documentation best practices`: http://docness.readthedocs.org/