benoitbryon/docness

Tips, tricks and conventions about documentation content.

docness's Issues

Recommend introduction (scope and goal) on each document

When a reader browse the documentation, he wants to quickly know what a document talks about. So that he can avoid reading something which he doesn't need to.
It's particularly important when looking for something: the topic of the document tells the reader whether he is looking at the right document or not.

So: write an introduction on each document.
Introduction should tell:

• topic
• scope
• goal

Change project name

"documentation-best-practices" seems a bit presumptuous. It is a set of practices that sound good to some people (which is, currently, almost only the author).

So, let's change the project name. Consider this material as yet another project about documentation. Don't pretend to be the only one.

Recommend convention about language

Documentation language is a recurrent topic.
English language is usually chosen in open-source projects because english is de facto standard on in computer science.

But for corporate projects, teams often wonder whether to use their natural language or english...

So:

• advise documentation writers to write down language convention in documentation
• advise documentation writers to argue about their choice if it is not english
• argue about "english" choice in this project : why is english a best practice
• if the choice is english, advise writers to put a link to this "best practice" project (don't repeat external convention)

Move project to a wiki or some other collaborative edition platform

See https://github.com/benoitbryon/documentation-best-practices/blob/master/docs/documentation-is-part-of-product.txt#L41

Is this project a true documentation? There is no related product. Should this project be released, with versions?

Maybe it would be more suitable to move to some collaborative edition platform, such as a wiki.

Recommend conventions **with** feedback, or even replace conventions by feedback

Documentation can contain conventions, but...

• conventions should be associated to feedback
• whenever possible, conventions should be replaced by feedback

Conventions

Documentation can contain conventions.

As an example, with Python programming language, PEP8 deals with coding standards. It is a convention.
One could write "use PEP 8" in the documentation.

Conventions with feedback

When conventions are written in the documentation, risk is that they are not applied.
So, here at "documentation best practices", recommend that some kind of monitoring is associated to conventions.
So that users receive positive or negative (measurable) feedback depending on conventions.

As an example, some Python coding standards can be checked with tools like pep8, pyflakes or pylint.
So, let's use these tools to check code quality and get feedback about it.
In documentation, one could write commands to run before a commit in order to check code against coding standards.

Make sure convention gives feedback

Even if the convention is written in the documentation, there is a risk it is unused.
So we'd like to add some automation to check convention status.

As an example, if you invite the user to check his code against pep8, you also give him the opportunity to avoid it.
So, let's write a pre-commit hook or a continuous integration test:

• developer doesn't have to remember
• code is always checked against coding standards.

Replace convention by feedback

But is the convention really needed in the documentation?
Can we make convention so obvious there is no need to enunciate it?
Whenever possible, we should.

As an example, PEP8 is a Python convention. Every Python developer should know and follow PEP8. So, there is no need to talk about it in the documentation.
And if a developer doesn't follow it, then negative feedback is provided by pre-commit hook or continuous integration service.

As another example, we could have enunciated a convention about code coverage.
But we had better plug some coverage plugin into continuous integration service.
So we can get:

• relative feedback with coverage evolution in history
• binary feedback if we tell the continuous integration service that "less than 75% code coverage is not acceptable".

It's pig VS chicken

Do you know about the chicken and the pig?
By writing a convention in the documentation, you were involved.
By making sure the convention is applied, you get committed.

Recommend style-guide

Documentation should use some style-guide convention.
Such as http://documentation-style-guide-sphinx.readthedocs.org for Sphinx-based documentations.

For Sphinx users, recommend pylit

Try http://pylit.berlios.de/ and, maybe, recommend it to create "productive" documentation.

Use hyperlinks, avoid repeating existing external ressources

One recommendation related to https://github.com/benoitbryon/documentation-best-practices/blob/master/docs/channel-communication-flow.txt is to use links rather than repeating existing ressources (documentations, conventions, standards, tutorials, scripts...).

Reference/join/merge Eric Holscher's work at readthedocs.org

See http://ericholscher.com/blog/2012/jan/22/why-read-docs-matters/

Recommend proxy-cache usage for valuable external ressources

One recommendation related to https://github.com/benoitbryon/documentation-best-practices/blob/master/docs/channel-communication-flow.txt is to use links rather than repeating existing ressources (documentations, conventions, standards, tutorials, scripts...).

But there is a risk that external content becomes obsolete or disappears:

• content changed
• content moved
• content deleted
• networking issue (offline mode?)

So, a proxy-cache could help:

• backup when content is unavailable
• warning when content is updated (review of changelog may be required)

Make it possible to reference recommendations with links

Number recommendations or make sure links can be created to reference recommendations.

As an example, in a code review, one can reference recommendations in some tickets like this:

Convert installation instructions to a script, as recommended in https://github.com/benoitbryon/documentation-best-practices/blob/master/docs/channel-communication-flow.txt#L14

... where the link readability is improved.

Requires the recommendations to be limited to a clear scope.

Wrong URL in docs/convention/documentation-language

http://documentation-best-practices.readthedocs.org/conventions/index.html#english_is_standard if wrong.

http://documentation-best-practices.readthedocs.org/en/latest/conventions/documentation-language.html#english-is-standard-for-software-development should be better.

Recommend external channel for generic recipes (articles, scripts)

A documentation is related to a project. Anything that is not specific to the project should not be in the project's documentation.

It's a common practice to write down recipes in the documentation, so that collaborators can follow the recipe to perform some task. That's ok when the recipe is specific to the project. But when it is a general recipe, that's a bad idea. The writer had better reference an external ressource than embed it inside the project's documentation.

As an example:

• To deploy the project on a server, some network configuration has to be done on the server. Let's say it is some DHCP configuration.
• If no article (blog post, documentation...) exists about this operation, let's write and publish one.
• In case of DHCP configuration, I guess many ressources already exist.
• Then, in project's documentation, add an hyperlink to this external recipe.

Why?

• Think open-source: more contributors allows better quality.
• If it is not specific to project, it could be reused in other projects, by other people. So share it!
• Most of the time, an external ressource already exists... don't rewrite it. Spend your time on more valuable actions.
• If external ressource is incomplete or has issues, contribute!
• If no external ressource exists, let's create one! you may become famous :) In fact, you may attract contributors!

See also #7 and #6.

Recommend to document alternatives (similar projects)

List similar projects in the documentation.

Benefits:

• by searching alternatives, you may find other projects that already fit your needs!
• if you do it early, it's easier to use another project or pull-request your features. Then you may need a merge.
• people like to know alternatives
• focus on differences with your project. If you created a new project instead of contributing to others, you certainly have some valuable difference (if not, you do you really need to create yet another project?)