Community mailing list archives

community@mail.odoo.com

Re: Reflection about documentation.

by
Vauxoo S.A. de C.V., Nhomar Hernandez
- 08/14/2014 11:37:54

On Thu, Aug 14, 2014 at 10:18 AM, Daniel Reis <dgreis@sapo.pt> wrote:
Anyone can collaborate using PRs without the need for technical skills. Probably that's enough.
In case it feels like there's a bottleneck there, remember that GitHub allows to set write-access users per Repo, so it could be decided to have a broader committer policy on the docs repo.

Well, github do a lot of thing for you without even understand what a commit is, even all proffessionals editor tools has concept of versioning and so on.

IMHO (may be I am wrong but I am almost sure) the unique middle point is "Ask for more functional knowledge to programmers" but it must be the viceversa too, "functional who want to collaborate needs to learn at least the minimal things (fork, change, commit and make a PR graphically on github)." We the developers can help them on tht in the same way around they will help us to make correctly our contextual helping.

To be really synergic, any position can be based on "I don't want, I can't, It is not my responsability" it is a matter of use the right words some times.

Said that... I am seeing a lot of move here but probably we need to explain a little better for functional guy what is a "toc" (which is what needs to be filled on the pad).

TOC (from table of content) is the "List" of topics (it means exactly what in a  bok it means, and that what we should fill as a first step on the pad.

What is NOT a TOC?: Explanations of the intention of the book and so on.

What is the objective of the toc we are filling today?

Ok in the actual book (published here [https://doc.odoo.com/7.0/]) we have 10 "books" thats the "main toc".

Every book has his own "toc":

The list of books is here:


The files per book are inside one folder per chapter (let's say 0, 1, 2 .....)

The "toc" per book is built "automagically" with the "titles".... you can see graphically this toc per book here:

Functional: 

Technical:


Community:


etc....

LEt's left out "community" (it will be migrated to wiki pages on OCA).
Let's left out "technical" (it will be inside the code and other project or it is in discussion between technical guys).

Let's talk about "functional":

The functional book needs be "structured" and the first step is the "TOC", but based on the actual one is better, if you think the actual one need to be changed, moved, remove, and so one, "cool" that's the point.

On this book "The user is the customer" and IMHO, we need to be "as conceptual as we can" ore than "procedural".

May be we can build a "procedural book" based on the "How to's" on the actual help platform.

Why did I explain this last part?.

TO avoid a little the discussion between "it is so technical or not" I think it is clear "The user is the key" in the "Functional Approach".

Let's make the TOC "Please contribute here":


What can be cool in the "toc":

- Links to books you think are making a good job to copy structures.
- Specific topics (if we refer to the "actual" or a "benchmark" of other books it can help to understand what will be there).

Our job technically speaking will be migrate the actual book to "something
like" the first draft of toc. Thanks to the power of github, git, sphinx and our programming knowledge it will not be an "inamovible" decision we can change in the middle to be improved day by day.

Some advantjes of understand this structure:

1.- Every module/app can have its own "toc" and can be written in plain text and inserted in the book in any time and referenced infite times when it is necesary "to be re-printed, inserted or modified".

2.- We can document separately in our own topic, "alá wikipedia".

3.- Merge - PR - revision can be controlled.

4.- One time we understand 1 model of well documented way to document we will be able to help any community in the world with this approach.

5.- You as functional can "fork" the book, work on it improve for your own internal process and when it is ready you can propose the merge.

6.- It can be "customized", inside your own implementeation.

7.- It can be "published" for your customers with 1 command in PDF or printed.

8.- It can be used as slides....

9.- It can be watched in HTml thanks to sphinx an its similarity to md (or the similarity of md to rst).

It can be it can be ......

The TOC is the key ;-)

BEst regards and really thanks for contribute, we will be a better world a page at a time ;-).







--
Nhomar Hernandez
CEO Vauxoo.
Twitter: @nhomar
Odoo Gold Partner