Mailing-List: contact chemistry-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: chemistry-dev@incubator.apache.org
Received-SPF: pass (nike.apache.org: domain of florian.mueller@alfresco.com
 designates 207.126.144.135 as permitted sender)
Message-ID: <4D3D5852.9080306@alfresco.com>
Date: Mon, 24 Jan 2011 10:45:38 +0000
From: =?ISO-8859-1?Q?Florian_M=FCller?= <florian.mueller@alfresco.com>
User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.6; en-US;
 rv:1.9.2.13) Gecko/20101207 Thunderbird/3.1.7
MIME-Version: 1.0
To: chemistry-dev@incubator.apache.org
Subject: Re: Documentation clean-up after 0.2.0?
References: <11E8705F4573E64FB42C724ADC742F6F03440251@MUCXGC2.opentext.net>
In-Reply-To: <11E8705F4573E64FB42C724ADC742F6F03440251@MUCXGC2.opentext.net>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 8bit

Hi all,

I fully agree, we have to tackle the documentation and clean up the webseite. 

@Jens: Feel free to fix the Mailing List, Issue Tracking, etc. issues.

@Paul: If I remember that correctly, some of the navigation inconsistencies are caused by the Confluence export script and need manual interaction.
Do you recall what we have to do to trigger a full export?

@OpenCMIS: From my perspective, the JavaDoc and the Client API guide are the most urgent pieces.
Who can of you can spend time on documentation? I can take a share but I need to know where to start. It doesn't make sense if we all do JavaDoc, for example.


And I would like to add a related topic:
Confluence will be phased out and Apache CMS will take over [1][2]. Markdown is the mark up language for Apache CMS. 
Would it make sense to write our documentation in Markdown then?


Cheers,

Florian


[1] https://blogs.apache.org/infra/entry/the_asf_cms
[2] http://wiki.apache.org/general/ApacheCms2010


On 24/01/2011 09:20, Jens H�bel wrote:
> Hi Chemistry,
> 
> great to see that we have got the 0.2.0 release out and that the Python library makes really good progress.
> 
> To catch up with all the nice code we have now in my opinion we should focus our efforts for the next weeks to clean-up our documentation mess. I find it hard to find information there: Navigation and structure is inconsistent. There are some TODOs open for months, parts are not updated  and we have gaps with stuff that is not documented at all.
> 
> I got feedback like this from a couple of people working in my environment and I think the project is only as good as the documentation is.
> 
> Some examples:
>   - Java and Python have a completely different style and navigation
>   - Some parts of the opencmis section in navigation pane are not opencmis specific: Mailing List, Issue Tracking, Source Code
>   - The .Net section disappears after clicking on some of the sections (e.g. cmislib).
>   - Query model has changed since 0.1.0 but has not been updated.
>   - From my impression the Client API is the most demanded part of opencmis and unfortunately this part still has major gaps in documentation. We need an introduction, we need to explain the design, the caching the refresh mechanisms. We had lengthy discussions in the mailing list, we have improved the code, but none of this seems to be documented. We have some examples, but we need more.
>   - What is the difference between OpenCMIS Guides and the OpenCMIS cookbook?
>   - Workbench has no documentation at all (how to install web start, config options)
> 
> Is there a chance a to use a navigation pane like this here: http://confluence.atlassian.com/display/DOC/Confluence+Documentation+Home?
> 
> Any thoughts on this by the community? Any ideas how to improve or proceed? Perhaps we can find an agreement on the top level structure on the mailing list and then fill the gaps as we find time?
> 
> Jens
>