benoitbryon / docness Goto Github PK
View Code? Open in Web Editor NEWTips, tricks and conventions about documentation content.
Tips, tricks and conventions about documentation content.
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:
"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.
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:
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.
Documentation can contain conventions, but...
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.
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.
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:
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:
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.
Documentation should use some style-guide convention.
Such as http://documentation-style-guide-sphinx.readthedocs.org for Sphinx-based documentations.
Try http://pylit.berlios.de/ and, maybe, recommend it to create "productive" documentation.
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...).
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:
So, a proxy-cache could help:
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.
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:
Why?
List similar projects in the documentation.
Benefits:
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.