Re: Reflection about documentation.

by

Hertford Developments Limited, Kurt Haselwimmer

- 08/28/2014 07:48:58

Leonardo,

thanks for this build - it really helps accessibility. I presume that the display format (eg with index that highlights where you are on the page) is a feature of readthedocs and just looks a bit like odoo because they may both be using bootstrap. It's a very clear presentation that it would be good to have within odoo - eg for viewing, er, documentation. I don't know about you but I find some of the odoo presentation a little hard to make out - eg comments on the forums are so light as to be almost invisible - but maybe it is my eyes or monitor ?

I don't know if you saw it, but Raphael Collect (rco) has recently
committed huge documentations rewrite commits to the 8.0 branch. You
can read this (unfinished) brand new documentation directly on GitHub,
or if you prefer I managed (with some hacks) to make it build on
readthedocs, you can find it here.
http://odoo-80.readthedocs.org/en/latest/
2014-08-27 11:06 GMT+02:00 David Beal <david.beal@akretion.com>:
> Hi all,
>
> As it was said, maintain functional doc for final users has a huge cost.
> This documentation already exist, like here
> https://www.odoo.com/apps/trunk/crm/

>
> But final users have no access to it (you need to have admin rights to see
> it)
>
> Final users should to have access it directly from object/model screen.
>
> Maybe a contextual 'help' menu according to model should be available for
> users
>
> This menu could open a new tab or popup which display the list of all the
> modules which have impact on the model/object with their descriptions like
> for crm app above.
>
> The Contextual documentation is far the best doc that we can produce.
>
> .rst is a really good format for documentation
>
> We have almost all the tools under hands
>
> Only miss the glue
>
> my 2 cents
>
> PS : those who want a complete doc, can contribute, we are waiting for ...
>
> David BEAL - Akretion - Odoo Development / Integration
> +33 (0)6 67 22 86 89 - +33 (0)4 82 53 84 60
>
>
> 2014-08-25 17:30 GMT+02:00 David Arnold <dar@devco.co>:
>>
>> For those who are lazy to read askslashdot (it's worthwhile however,
>> because those people vastely seem to have maintained a very strong critical
>> sense), the discussion is quite inline with what we have been discussing
>> herein. It seems, however, that Fabien's strategic approach about User Docs
>> (I hope all have understood it by now) has been validated, as well as many
>> of the other concepts herein discussed, urging however not to only rely on
>> it not even for users only. The retionals provided are very diverse and
>> intersting and give a good overview of the limitations and implications of
>> documentation investment and its impact on the ecosystem.
>>
>> As Stephen Mack reported on the sister thread, something is done here:
>> https://github.com/odoo-dev/odoo/tree/8.0-newnewdoc-xmo

. I think, everyone
>> else than Odoo leading this effort, would be a really, really bad idea.
>>
>> Sidenote/Reminder: I did not read one single time the distinction between
>> "funcional" and "technical" doc on slashdot, it seems indeed an tendentially
>> isolated concept of our context. I still doubt this syntactical distiction
>> is anything more than arbitrary in an integrated systemic view. Correct me
>> if I'm wrong.
>> Saludos Cordiales
>> David Arnold
>>
>> _______________________________________________
>>
>>
>> Mailing-List: https://www.odoo.com/groups/community-59