Documentation clean-up after 0.2.0?
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
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
Re: Documentation clean-up after 0.2.0?
On Mon, 24 Jan 2011, Florian Müller wrote: 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? If you're interested in moving to the new CMS (which amongst other things would give you more control over the navigation, and quicker publishing of changes), I can help out with the migration Nick
RE: Documentation clean-up after 0.2.0?
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:florian.muel...@alfresco.com] Sent: Montag, 24. Januar 2011 11:46 To: chemistry-dev@incubator.apache.org 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
