Developer manual stub now available

[Mikko Ohtamaa]

Hi,

I have created the long awaited dev man stub at

http://plone.org/documentation/manual/developer-manual

It has all chapter level headings, but is mostly empty otherwise. How can I share it so that everyone is able to edit it... or at least browse intermediate results?

Cheers,
Mikko

[Israel Saeta Pérez]

Mikko Ohtamaa wrote:
> Hi,
>
> I have created the long awaited dev man stub at
>
> http://plone.org/documentation/manual/developer-manual
>
> It has all chapter level headings, but is mostly empty otherwise. How can I
> share it so that everyone is able to edit it... or at least browse
> intermediate results?


Hello Mikko,

First of all, congrats for your unstoppable initiative!

You should be able to share it with anybody through the "Sharing" tab,
but I'm not sure if it does work correctly yet since we still have some
issues with the current stable release of PHC. Everything should be
easier once we split current documentation into knowledgebase (open
wiki-style zone) and "core" documentation. Steve McMahon is working on
it. Please ask me if you're interested in helping with testing.

Regarding the idea of a Developer Manual, I'm ok with creating it as a
single manual if you feel it makes collaboration easier. But I'd prefer
to spread later the different topics into several manuals. Maybe that's
because I prefer to think about each topic in a more "modular" way,
rather than an ordered list of things to read and learn.

Additionally, some of the contents you outlined, like portlets or forms,
are already present in other manuals. Why not extending these manuals
instead of creating a new one?

-- israel


------------------------------------------------------------------------------
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Martin Aspeli]

Israel Saeta Pérez wrote:
> Mikko Ohtamaa wrote:
>> Hi,
>>
>> I have created the long awaited dev man stub at

w00t :)

> Regarding the idea of a Developer Manual, I'm ok with creating it as a
> single manual if you feel it makes collaboration easier. But I'd prefer
> to spread later the different topics into several manuals. Maybe that's
> because I prefer to think about each topic in a more "modular" way,
> rather than an ordered list of things to read and learn.
>
> Additionally, some of the contents you outlined, like portlets or forms,
> are already present in other manuals. Why not extending these manuals
> instead of creating a new one?

I think maybe the context got lost here. From what I can tell, this is
the "API reference" idea we were talking about a while back. Maybe we
should rename it?

The idea is to have short code snippets and examples for people looking
for Plone's "API". More in-depth background and step-by-step guides
should still go in separate manuals.

If this was a book, think of the other tutorials/manuals as chapters,
and this as the "quick reference" appendix.

We can and should link to more in depth manuals when available from the
relevant sections, too.

Martin

--
Author of `Professional Plone Development`, a book for developers who
want to work with Plone. See http://martinaspeli.net/plone-book


------------------------------------------------------------------------------
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Israel Saeta Pérez]

Martin Aspeli wrote:

> Israel Saeta Pérez wrote:
>> Mikko Ohtamaa wrote:
>>> Hi,
>>>
>>> I have created the long awaited dev man stub at
>
> w00t :)
>
>> Regarding the idea of a Developer Manual, I'm ok with creating it as a
>> single manual if you feel it makes collaboration easier. But I'd prefer
>> to spread later the different topics into several manuals. Maybe that's
>> because I prefer to think about each topic in a more "modular" way,
>> rather than an ordered list of things to read and learn.
>>
>> Additionally, some of the contents you outlined, like portlets or forms,
>> are already present in other manuals. Why not extending these manuals
>> instead of creating a new one?
>
> I think maybe the context got lost here. From what I can tell, this is
> the "API reference" idea we were talking about a while back. Maybe we
> should rename it?
>
> The idea is to have short code snippets and examples for people looking
> for Plone's "API". More in-depth background and step-by-step guides
> should still go in separate manuals.
>
> If this was a book, think of the other tutorials/manuals as chapters,
> and this as the "quick reference" appendix.
>
> We can and should link to more in depth manuals when available from the
> relevant sections, too.

Ah, if this the "API (quick) reference", then I'm ok with placing
everything here and link to more in-deep manuals where needed.

I agree with others on this would better be generated from code, ideally
from interfaces. This way we wouldn't have to revisit the API reference
everytime a developer adds/removes a method but it would be her/him who
updates the interfaces code and regenerates the API reference.

-- israel


------------------------------------------------------------------------------
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Martin Aspeli]

Israel Saeta Pérez wrote:

> I agree with others on this would better be generated from code, ideally
> from interfaces. This way we wouldn't have to revisit the API reference
> everytime a developer adds/removes a method but it would be her/him who
> updates the interfaces code and regenerates the API reference.

Can we please not re-open this discussion? It took enough time as it was
last time.

It's not going to work. Don't get me wrong - having generated
documentation from interfaces and a single browsable repository ala
api.plone.org is a great idea. But it's not sufficient. You can't see
the woods from the trees, and you don't know where to look for the
things you need. We need something like this manual that is organised
around the things people want to achieve, rather than the historical
names and locations of various bits of Plone's internal code.

Martin

--
Author of `Professional Plone Development`, a book for developers who
want to work with Plone. See http://martinaspeli.net/plone-book


------------------------------------------------------------------------------
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Mikko Ohtamaa]

Martin Aspeli wrote:

> Regarding the idea of a Developer Manual, I'm ok with creating it as a
> single manual if you feel it makes collaboration easier. But I'd prefer
> to spread later the different topics into several manuals. Maybe that's
> because I prefer to think about each topic in a more "modular" way,
> rather than an ordered list of things to read and learn.

> Additionally, some of the contents you outlined, like portlets or forms,
> are already present in other manuals. Why not extending these manuals
> instead of creating a new one?

I hope that I can simply link in to authoritative documentation if available. But you still need to define the body of knowledge for Plone somewhere so you know what all kind of techniques exist :) For some content I have created myself I plan to simply delete the old pages and fuse it directly to the new documentation.

I think maybe the context got lost here. From what I can tell, this is
the "API reference" idea we were talking about a while back. Maybe we
should rename it?

The idea is to have short code snippets and examples for people looking
for Plone's "API". More in-depth background and step-by-step guides
should still go in separate manuals.

Yes. I am open to all suggestions. I used name "developer manual" because Django et al where using this term. Maybe "programming guide?" "API reference" is often reserved for the documentation generated from the source code.

I think there still needs to be little, just little, general "fluffy talk" in some sections (e.g. transaction model).

Cheers,
Mikko

[Mikko Ohtamaa]

Hi,

To lessen the barrier to get contributions to programming documentation I have sketched the following process outline below. Can you all check it is ok? I am especially unsure about issue tracker part (I don't know how docteam uses issue tracker).

The text will appear as one of the first pages of dev doc.

Documentation process

This documentation is written and maintained by volunteering experts.
It is incomplete due to constant change in the surrounding projects.
To keep up with the change we hope you can help us to improve the documentation
and contribute to this documentation.

Documentation oriented problem solving approach
-----------------------------------------------

In some point, you will encounter information which is missing here but you think it shoud
be here. If you manage to solve your problem we'd like to have few lines written about
it how did you solve it, so that other can benefit from your hard work. Also,
this documentation will serve as your memo when you'll face the same problem
again after longer period of time.

This process is called documentation oriented problem solving.
Its goal is to avoid the need to resolve the same problem twice.

To contribute this documentation you can

1) Ask permission to edit this document directly (plone.org account needed)

2) Use "Add comment" feature at the bottom of the page (plone.org account needed). Note that this feature is not support
   forum and it is not always likely anyone will give answers to your questions.

3) Open a new ticket in `Plone bug tracker <https://dev.plone.org/plone>`_ (plone.org account needed).
   Use component ''documentation'' and use summary "Contribution to developer documentation".

4) Send email to `Plone documentation team email list <http://plone.org/support/forums/docs>`_ (subscription needed)

Contributions needed
--------------------

Below is the list of documentation and references we'd like to see

- New code snippets and system descriptions

- Links to external documentation

- Links to component READMEs

- Links to blog posts talking about particular issue

- Linsk to email list dicussions

- Links to source code (directly to the version control)