search

plone / Products.CMFPlone

The core of the Plone content management system
https://plone.org
GNU General Public License v2.0
240 stars 184 forks source link

Code snippet examples for the documentation #1346

Open pigeonflight opened 8 years ago

pigeonflight commented 8 years ago

In many scenarios there is a need for more specific examples. A specific use case I've had is importing images into Plone using the plone.api. The plone.api docs are light on the specifics of doing this.

Often these real world examples can only be identified when they are needed. As a result they don't necessarily get captured in the context of the formal documents, instead they are stored as snippets by experienced practitioners.

Recently I came across a repository which Nathan Van Gheem shared with the collective. It has many useful code snippets (real world examples), https://github.com/collective/code-snippets

I've proposed Plan A and Plan B below to capture what can be done with these snippets. I think this task could make the basis of a very focused documentation related Plone sprint.

Plan A

possibly 64 man hours

I am proposing that the snippets be evaluated and then inserted as examples in relevant parts of the documentation. This is not trivial, they can't just be cut and pasted verbatim into the context of the documentation, but a keen eye reviewing them could make the right adjustments for the context of a particular part of the documentation. It will also require the skill of figuring out which part of the documentation a snippet best addresses.

There are about 16 snippets and I think it could take 3 to 4 hours per snippet if we're doing this properly. Having these good examples in context would be the most desirable scenario.

Plan B

possibly 32 man hours

Another option, less desirable but faster, would be to create a "recipes/snippets/cookbook" section of the docs and just add additional explanatory notes to the snippets.

gforcada commented 8 years ago

We can have B and A: i.e. make a first "quick" move and then keep moving them to the right place as we see fit.

I'm not sure if we want to move the code there or only link/embed them.

If we keep the code in the repository its easier to make improvements on them and at the same time make it easier to embed (into docs.plone.org) and copy&pasting.

gyst commented 8 years ago

Please note that some of these snippets have corresponding plone.api methods, in which case it's better to reference plone.api. login-as-admin -> http://docs.plone.org/develop/plone.api/docs/env.html#switch-user-inside-a-block rename-file -> http://docs.plone.org/develop/plone.api/docs/content.html#rename-content

Some others are patially overlapping with plone.api and might be candidates for extending the api: find-text -> http://docs.plone.org/develop/plone.api/docs/content.html#find-content-objects

Also, while this is an interesting collection, I'm sure there's a lot more snippets that would be worthy of harvesting. Everybody rgreps their old projects when you hit something and think: I solved this last year, didn't I? Exploring this might be interesting in a sprint.