chemistry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Florian Müller <florian.muel...@alfresco.com>
Subject Re: Documentation clean-up after 0.2.0?
Date Mon, 24 Jan 2011 10:45:38 GMT
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
> 


Mime
View raw message