Community mailing list archives

community@mail.odoo.com

Re: OCA modules Documentation

by
initOS GmbH, Torsten Francke
- 11/19/2014 11:00:30
Hi Yannick,

a user documentation. Sorry i mixed it up with how-to-contribution
documentation. Not carefully reading. So that is a diffrent topic that
this page has no love ;)

So back to your topic. On the magento-connector c2c use Sphinx and put
it in the /doc dir. So you can create a webside from it and managed it
in git. It is possible to read inside github, but you have not all links
what will be autogenerated.

Compare:
https://github.com/OCA/connector-magento/blob/7.0/magentoerpconnect/doc/index.rst
with:
http://odoo-connector.com/

So i think using .md files is also a option. I m not so familiar with
github wiki. You can edit it. Fork it but not creating pull request. So
if you want a pull-request / review feature. Then it seems like we can
not have a github wiki.

Kind Regards

Markus

On 18.11.2014 13:03, Yannick Buron wrote:
> Hello Markus,
> 
> This very important page shall only be used to display the OCA
> guidelines according to me, not the documentation specific to each
> project. In general, I'm against placing the user documentation in the
> OCA website, only project manager can edit the OCA pages and this will
> clearly slow the contributions to documentation. Moreover, I'd really
> like to track the contribution to the documentation with github stats.
> 
> Except maybe if we decide to use the same process that Odoo SA, with a
> documentation based on the Q&A forum but I see it as complementary.
> Contributors shall work on a structured documentation (For Community
> Verticalisation I have plenty of people wishing to work on
> documentation, our problems is more the lack of seasoned developers),
> but we shall use the OCA Q&A forum to maintain an FAQ on the OCA website
> I think.
> 
> Regards,
> 
> *Yannick Buron*
> Founder
> +33 (0) 6 70 74 52 26 | _yannick.buron@gmail.com
> <mailto:yannick.buron@gmail.com>_
> My blog : www.disruptingworld.me/ 
> 
> <img alt="Twitter" src="cid:part3.08000902.09030006@gmail.com"
> height="20px">  LinkedIn src="cid:part5.07070603.00020507@gmail.com" height="20px">
> Github src="cid:part7.00000604.01070008@gmail.com" height="20px">
>  Facebook src="cid:part9.08010803.03060805@gmail.com" height="20px">
>  Google src="cid:part11.02020402.05030601@gmail.com" height="20px">
>  RSS src="cid:part13.07000800.08080805@gmail.com" height="20px">
> 
> 
> YOLO Consulting
> Building the tools we need
> 98 Avenue du general pierre billotte BatD
> 94000 Creteil
> www.yolo-consulting.net  |
> www.empower-us.net  | www.wikicompare.info
> 
> 
> Le 18/11/2014 09:57, Markus Schneider a écrit :
> <blockquote cite="mid:546B08B5.4040009@initos.com" type="cite">
> 
> http://odoo-community.org/page/website.how-to
> 
> Is not complete, but we should collect all information there instead
> having wikis in each github repositories.
> 
> The problem only some board member can edit this page. So may be have a
> wiki/etherpad page somewhere to complete the documentation and stable
> release where moved to the website.
> 
> Kind Regards
> 
> Markus
> 
> On 18.11.2014 09:42, Yannick Buron wrote:
>> Hello friends,
>> 
>> I have a question regarding documentation for OCA repositories. I have
>> some contributors for the Community Verticalization who would like to
>> start writing documentation about it but I don't which is the official
>> guidelines of the OCA on this matter.
>> 
>> Should we use the github wiki? Or put .md files directly in the repo?
>> Shall the use of services like readthedoc be encouraged (I don't really
>> know them, but from what I understand it synergize well with .md file in
>> repo) ?
>> 
>> Somes are suggesting we place code /module related informations into the
>> .md files and more user / admin related content into the wiki because
>> it'd be easier for the pictures. I personally think it's best the place
>> everything in .md files.
>> 
>> What do you think? What is the recommendations of the OCA? Sorry if I
>> missed an earlier discussion about it.
>> 
>> -- 
>> *Yannick Buron*
>> Founder
>> +33 (0) 6 70 74 52 26 | _yannick.buron@gmail.com
>> <mailto:yannick.buron@gmail.com>_
>> My blog : www.disruptingworld.me/ 
>> 
>> <img alt="Twitter" src="cid:part3.01000006.01090500@gmail.com"
>> height="20px">  LinkedIn src="cid:part5.00000303.02020308@gmail.com" height="20px">
>> Github src="cid:part7.04030607.06060401@gmail.com" height="20px">
>>  Facebook src="cid:part9.03050705.08080201@gmail.com" height="20px">
>>  Google src="cid:part11.03030308.00030302@gmail.com" height="20px">
>>  RSS src="cid:part13.06020209.05080501@gmail.com" height="20px">
>> 
>> 
>> YOLO Consulting
>> Building the tools we need
>> 98 Avenue du general pierre billotte BatD
>> 94000 Creteil
>> www.yolo-consulting.net  |
>> www.empower-us.net  | www.wikicompare.info
>> 
>> 
>> _______________________________________________
>> Mailing-List: https://www.odoo.com/groups/community-59
>> Post to: mailto:community@mail.odoo.com
>> Unsubscribe: https://www.odoo.com/groups?unsubscribe
>> 
> 
> -- 
> Dipl.-Comp.-Math. Markus Schneider
> Softwareentwickler
> 
> initOS GmbH & Co. KG
> An der Eisenbahn 1
> 21224 Rosengarten
> 
> Mobil:   +49 (0)172 2303699
> Phone:   +49 (0)4105 5615613
> Fax:     +49 (0)4105 5615610
> 
> Email:   markus.schneider@initos.com
> Web:     http://www.initos.com
> 
> Geschäftsführung:
> Dipl. Wirt.-Inf. Frederik Kramer & Dipl.-Ing. (FH) Torsten Francke
> Haftende Gesellschafterin: initOS Verwaltungs GmbH
> 
> Sitz der Gesellschaft: Rosengarten – Klecken
> Amtsgericht Tostedt, HRA 201840
> USt-IdNr: DE 275698169
> Steuer-Nr: 15/205/21402
> 
> _______________________________________________
> Mailing-List: https://www.odoo.com/groups/community-59
> Post to: mailto:community@mail.odoo.com
> Unsubscribe: https://www.odoo.com/groups?unsubscribe
> 
> 
> _______________________________________________
> Mailing-List: https://www.odoo.com/groups/community-59
> Post to: mailto:community@mail.odoo.com
> Unsubscribe: https://www.odoo.com/groups?unsubscribe
> 

-- 
Dipl.-Comp.-Math. Markus Schneider
Softwareentwickler

initOS GmbH & Co. KG
An der Eisenbahn 1
21224 Rosengarten

Mobil:   +49 (0)172 2303699
Phone:   +49 (0)4105 5615613
Fax:     +49 (0)4105 5615610

Email:   markus.schneider@initos.com
Web:     http://www.initos.com

Geschäftsführung:
Dipl. Wirt.-Inf. Frederik Kramer & Dipl.-Ing. (FH) Torsten Francke
Haftende Gesellschafterin: initOS Verwaltungs GmbH

Sitz der Gesellschaft: Rosengarten – Klecken
Amtsgericht Tostedt, HRA 201840
USt-IdNr: DE 275698169
Steuer-Nr: 15/205/21402