That's a good point. I wasn't aware of this. It then probably makes more sense to do the transition first and then the update... otherwise we need to touch it twice.
Jens -----Original Message----- From: Florian Müller [mailto:[email protected]] Sent: Montag, 24. Januar 2011 11:46 To: [email protected] Subject: Re: Documentation clean-up after 0.2.0? 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 >
