On 27/05/2009, at 9:34 PM, Mikko Ohtamaa wrote:
> Developer manual writers are Python developers. Developer manual
> readers are Python developers. They are quite familiar with tools like
> SVN and Sphinx. The problem is the integration part.
>>
Totally agree and would also add that during the last plone conference
I ran a BOF session on gathering feedback on newbies find hard about
Plone. One item was that code snippets often didn't work.
If there is a way to keep the documentation maintainable in plone, but
testable at the same time then it could reduce the maintenance tasks
of the documentation team. With regard to official API documentation,
I personally think we should be pushing maintenance of this
documentation as much towards the developers as possible. If they
can't explain their changes they shouldn't be making them.
Martin Aspeli said...
>> I'm not interested in a debate to displace that. I'm even less
>> interested in fracturing our documentation into multiple sources that
>> can't be easily cross-referenced, searched or integrated in terms of
>> navigation and structure.
but what if we could have multiple sources that can be easily cross-
referenced, searched or integrated in terms navigation and structure?
As you say now is not the time to implement this, as it needs to well
thought out, but the really useful part of sphinx is the ability to
include elements from different sources and compile them into one
document.
If someone does write a well maintained doctest for part of the plone
core, and it fit's into the api manual, why rewrite it? If there was a
feature in kupu where you could "insert>linked content" and we could
get that content from the current plone code base, would it be such a
mess? Personally I think that it core coders saw that some of their
documentation was being exposed in an official manual it would lead
them to raise their game and create even more useful doctests.
Another example is the experiments Rok Garbas did with sphinx last
year where he blended written documentation with ATCT schema
documentation generated from the actual schemas. I'm not saying
generated documentation is always appropriate, just that when it is,
the result is more maintainable.
> This is totally correct. The result (content) is now more important
> than how it is done and I am pretty sure volunteers are happy to use
> Plone :)
+1 I will look though the mindmap after this weekend and pick some
topics to contribute. This effort is long overdue and I applaud Martin
for putting it back on the agenda.
------------------------------------------------------------------------------
Register Now for Creativity and Technology (CaT), June 3rd, NYC. CaT
is a gathering of tech-side developers & brand creativity professionals. Meet
the minds behind Google Creative Lab, Visual Complexity, Processing, &
iPhoneDevCamp as they present alongside digital heavyweights like Barbarian
Group, R/GA, & Big Spaceship.
http://p.sf.net/sfu/creativitycat-com
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs
