Community mailing list archives
Re: Reflection about documentation.by
and OCA protagonists:
thanks for your comments in the http://pad.odoo.com/p/doctoc, as I read them, I got the impression you see this effort as somewhat contrary to the Odoo ones, I think we should not think here in organizational terms or groups (neither Odoo, nor OCA, nor whatever)... People like Miguel, Kurt and myself come from another part of the user space, and this is not less than your target market. So what happens here is, that the target market is willing to move this ecosystem forward. This is probably a somewhat different situation. I don't want to know, if it is OCA, or Odoo, or whatsoever. Honours to internal structures, but they dont matter here. We just want a great documentation! This initative/momentum should not be hijacked by anyone at least not at this stage!
This is probably why we should avoid in this discussion the very technical details in order to not loose momentum from this side. I think we should work on http://pad.odoo.com/p/doctoc for now and improve or get it to some final stage (from the target market perspective!), so that Odoo itself can assign the tasks to make it happen.
@Nhomar, rearding http://pad.odoo.com/p/doctoc, if it is a copy of the original Table of Contents from v7 book, I would suggest a link to this table of content would do the job. I'm not really agreed on taking any path dependency in this issue. As it seems to me, the current documentation is a product of the past ecosystem, and it got no fame. So we should break with some bad practices in this ecosystem and take a fresh perspective from the target market, now that we have some people gathered together. I vote for "destroy to innovate" :) or "disruptive", we can say, too. but that's just my 2cts. By now many of you know my ecosystem concerns, but I'm not sure, if my arguments already become clear enough and penetrated... Actually part of this discussion is exactly inline with this concerns, which are mirrored by the already almost famous "head-in-the-sand" attitude (by Kurt) :)
@raphael: I think you also have this strategical perspective, and I understand exactly what you are trying to tell us and Odoo. And I think you are right! And I think the only way out is scale! (as you mentioned) and I think the prerequisites you mentioned (code quality for maintainance and low bug level) are critical issues here. So let's get this documentation right, so it will be inline with the future and prepare for this scale with its contribution in transparency and information flow! The whole ecosystem is dependent on this future, so to all: head out of the sand! Now! :)
@Kurt: I think you suggestion is very appealing. On thing about this, is if you look at the actual building of the documentation (in a technical sense), many parts are generated in an autmatic way, so Greg Moss would have to be integrated in such procedures, but he probably cannot do the complete job.
@Miguel: I understand your proposal perfectly, and it is indeed a very complete and professional one. To keep this paragraphe clean, I'll make some comments here (after the # in good old programming style :): https://gist.github.com/blaggacao/e8950263afab0d259202