Vision, tips and conventions about documentation content and workflows.
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.
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.
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.
This project mainly deals with documentation you write within a dedicated tool, i.e. not docstrings (documentation within code).
- 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
Download and install¶
git clone firstname.lastname@example.org/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.
They said “Eat your own dog food”, so follow:
In your commit messages, reference the ticket with some
Test and build¶
Build the documentation and review your work before commit.
|||(1, 2) https://github.com/benoitbryon/docness/issues|
|||(1, 2) https://github.com/benoitbryon/documentation-style-guide-sphinx|
|||(1, 2) http://docness.readthedocs.org/|
- Documentation usage
- Keep straightforward
- Be directive
- Documentation is part of the product
- Redirect information to the right communication channel
- Declare conventions