A few suggestions

10 messages

Martin Aspeli-2 () A few suggestions

Reply Threaded

All,

I'm not sure if I'm helping by throwing more suggestions into the mix
here, but I've tried to summarise my thinking on documentation in this
blog post:

http://martinaspeli.net/articles/on-plone-documentation

I regret not having been able to keep up with the (long!) discussions on
this list lately, so forgive me if I'm covering ground that's already
been covered, or missing something important.

I can't claim much authority over this team or this mailing list
anymore, but I'd encourage you all to focus on what's achievable with
minimal changes to our existing infrastructure, and bearing in mind the
rather limited volunteer resources we have available. It seems that
every six months or so, we have a long discussion about grand plans to
re-vamp all the documentation and the way we manage it, which lasts
right up until someone actually tries to implement these plans, and
finds that it's a huge job.

I hope the post above helps identify achievable goals. If you'd like to
discuss them, this thread may be a good place. If you'd like to take any
of them up, I'll provide the support I can.

Regards,
Martin

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

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

Graham Perrin () Re: A few suggestions

Reply Threaded

Martin Aspeli-2 wrote:

… to implement these plans … a huge job. … achievable goals. …

Martin, many thanks.

I agree, it is (and may continue to be) a huge job, but I believe that the goals are achievable.

Just one question. Where you say:

> if readers stumble across something, this is where they should be stumbling

— please, can you elaborate on that thought?

A Diigo-annotated view of <http://martinaspeli.net/articles/on-plone-documentation> includes highlights and sticky notes, and there's only one aspect that concerns me but as you say, it's

> a mistake to try and solve all the problems with "Plone documentation" in the same way

and I in no way discourage the approaches that don't suit me :)

(I confess, I haven't read the long threads in the forums … not that I'm disinterested, it's just a little too much to take in at the moment! And like Martin, I have a sense of déjà vu.)

A closing thought:

> … Barriers to entry should be low … Open the flood-gates …

To both of those points, +1
but I suggest that we should visualise something closer to a *single* flood gate. I'll make my thoughts on this a separate thread.

Regards
Graham

Martin Aspeli-2 () Re: A few suggestions

Reply Threaded

Graham Perrin wrote:
>
> Martin Aspeli-2 wrote:
>> … to implement these plans … a huge job. … achievable goals. …
>>
>
> Martin, many thanks.
>
> I agree, it is (and may continue to be) a huge job, but I believe that the
> goals are achievable.

Which goals? Mine, or the intermittently voiced grand vision of
re-drafting most of the documentation from scratch? The former is
definitely achievable. The latter, well... good luck. :)

> Just one question. Where you say:
>
>> if readers stumble across something, this is where they should be
>> stumbling
>
> — please, can you elaborate on that thought?

I just mean that we should highlight the "official" documentation where
we can, and make it clear that the "looser" how-to style documentation
is an ancillary source.

Martin

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

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

Dylan Jay-4 () Re: A few suggestions

Reply Threaded

> -----Original Message-----
> From: Martin Aspeli [mailto:[hidden email]]
> Sent: Monday, 24 November 2008 3:13 AM
> To: [hidden email]
> Subject: Re: [Plone-docs] A few suggestions
>
> Graham Perrin wrote:
> >
> > Martin Aspeli-2 wrote:
> >> . to implement these plans . a huge job. . achievable goals. .
> >>
> >
> > Martin, many thanks.
> >
> > I agree, it is (and may continue to be) a huge job, but I believe that
> the
> > goals are achievable.
>
> Which goals? Mine, or the intermittently voiced grand vision of
> re-drafting most of the documentation from scratch? The former is
> definitely achievable. The latter, well... good luck. :)

Having read the entire threads I'm struggling to think of anyone who's
suggested starting from scratch. I think what you've written up is not very
much different from what I've written up here as option 1
http://www.openplans.org/projects/plone-documentation/reorganizing-documenta
tion
Basically just splitting the current documentation into two parts, official
and community and overtime massaging the official into a manual form.

I think a lot of that discussion is heading in that direction and we
certainly need to achieve this in step by step way where is step isn't too
huge a leap.

> > Just one question. Where you say:
> >
> >> if readers stumble across something, this is where they should be
> >> stumbling
> >
> > - please, can you elaborate on that thought?
>
> I just mean that we should highlight the "official" documentation where
> we can, and make it clear that the "looser" how-to style documentation
> is an ancillary source.
>
> Martin
>
> --
> Author of `Professional Plone Development`, a book for developers who
> want to work with Plone. See http://martinaspeli.net/plone-book
>
>
> -------------------------------------------------------------------------
> This SF.Net email is sponsored by the Moblin Your Move Developer's
> challenge
> Build the coolest Linux based applications with Moblin SDK & win great
> prizes
> Grand prize is a trip for two to an Open Source event anywhere in the
> world
> http://moblin-contest.org/redirect.php?banner_id=100&url=/
> _______________________________________________
> Plone-docs mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/plone-docs

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

Graham Perrin () Re: A few suggestions

Reply Threaded

In reply to this post by Martin Aspeli-2

Martin Aspeli-2 wrote:

Graham Perrin wrote:
> I believe that the goals are achievable.

Which goals?

Let's say, for starters, 'personal goals'.

Where any two or more people have a shared vision _and_ high confidence in each other's ability to contribute and ultimately _realise_ the goal: 'shared goals'.

Somewhere in between: we have visions, grand and small, and such visions may serve as guidance — without necessarily becoming tasks that are binary (not done/done).

On one hand: there's the logical/human wish to defer or set aside (exclude from issue trackers) things that are non-binary. Something not done can become an itch, to be scratched. Get rid.

On the other hand: for a multitude of purposes, Trac excels. If we accept that some types of ticket might move across milestones over a period of months or years — specifically, if we can go with the reporting and flow that Trac makes possible — then (as suggested in your blog) we can begin to make greater uses of Trac.

we should highlight the "official" documentation where we can

+1

Not only content that's official.

Also, bring to the foreground the content that's _most current_.

Some of this is envisaged/implicit in <http://dev.plone.org/plone/ticket/8746> and with an eye on achievability, I currently view <http://dev.plone.org/plone/ticket/7831> as the feature most likely to ease and simplify things. (Personally, I don't slave over keywords, tags, categories, taxonomies etc. but if ticket 7831 is suitably progressed, I'm sure the results will be pleasing to all.)

and make it clear that the "looser" how-to style documentation is an ancillary source.

+1 to distinguishing.

I think that we (the community) should choose expressions, just a very few, that distinguish without diminishing.

(I view some of the content that's loose and/or ancillary as equal, or superior, to what's found (or represented) in the plone.org domain.)

... good luck. :)

Thank you :)

Markus Bleicher-4 () Re: A few suggestions

Reply Threaded

Graham Perrin wrote:

>> and make it clear that the "looser" how-to style documentation is an
>> ancillary source.
>>
>
> +1 to distinguishing.
>
> I think that we (the community) should choose expressions, just a very few,
> that distinguish without diminishing.
>
> (I view some of the content that's loose and/or ancillary as equal, or
> superior, to what's found (or represented) in the plone.org domain.)

I see it that way, too.

One thing I miss in this plone-docs mail storm is the idea that the
problem is not about documentation, but about Plone/Zope itself.
Maybe it is not about writing a how-to change the logo, but to make it
simpler, get some information hiding in place, so you don't have to
understand halve of the Zope/CMF/Plone stack to get it right. Which
makes it hard to explain.

Markus

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

Israel Saeta Pérez () Re: A few suggestions

Reply Threaded

On Wed, Nov 26, 2008 at 9:07 PM, Markus Bleicher wrote:

One thing I miss in this plone-docs mail storm is the idea that the
problem is not about documentation, but about Plone/Zope itself.
Maybe it is not about writing a how-to change the logo, but to make it
simpler, get some information hiding in place, so you don't have to
understand halve of the Zope/CMF/Plone stack to get it right. Which
makes it hard to explain.

I totally agree, but that's out of the documentation team's hands I guess.

-- israel

Israel Saeta Pérez

Dylan Jay-4 () Re: A few suggestions

Reply Threaded

> -----Original Message-----
> From: Israel Saeta Pérez [mailto:[hidden email]]
> Sent: Thursday, 27 November 2008 10:18 AM
> To: [hidden email]
> Subject: Re: [Plone-docs] A few suggestions
>
> On Wed, Nov 26, 2008 at 9:07 PM, Markus Bleicher wrote:
>
>
> One thing I miss in this plone-docs mail storm is the idea that the
> problem is not about documentation, but about Plone/Zope itself.
> Maybe it is not about writing a how-to change the logo, but to make
> it
> simpler, get some information hiding in place, so you don't have to
> understand halve of the Zope/CMF/Plone stack to get it right. Which
> makes it hard to explain.
>
>
>
> I totally agree, but that's out of the documentation team's hands I guess.

And I think it's in good hands. I was heartened by Martins talk at the
conference on simplifying Plone internals. I see our job as easing that pain
of the learning curve until such time as Plone is simpler. (of course in
reality Plone is a large system so can never be as easy to understand as
grok, bfg or rails for instance).

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

Markus Bleicher-4 () Re: A few suggestions

Reply Threaded

Dylan Jay wrote:

>> -----Original Message-----
>> From: Israel Saeta Pérez [mailto:[hidden email]]
>> Sent: Thursday, 27 November 2008 10:18 AM
>> To: [hidden email]
>> Subject: Re: [Plone-docs] A few suggestions
>>
>> On Wed, Nov 26, 2008 at 9:07 PM, Markus Bleicher wrote:
>>
>>
>> One thing I miss in this plone-docs mail storm is the idea that the
>> problem is not about documentation, but about Plone/Zope itself.
>> Maybe it is not about writing a how-to change the logo, but to make
>> it
>> simpler, get some information hiding in place, so you don't have to
>> understand halve of the Zope/CMF/Plone stack to get it right. Which
>> makes it hard to explain.
>>
>>
>>
>> I totally agree, but that's out of the documentation team's hands I guess.
>
> And I think it's in good hands. I was heartened by Martins talk at the
> conference on simplifying Plone internals. I see our job as easing that pain

I don't know his talk, but I hope that someone is moving something in
that direction. My expirience makes me a little wary, though: I think
everybody feels the pain handling this big intertwined thing, only that
bolting on new stuff is more fun (and in a relatively mature and
professional community like Plone's maybe more important: much more easy
to sell) than cleaning up. The transition from CMF skins to Zope3 views,
which added complexity but left all the old stuff in place (and was
probably necessary, it has to go in that direction), or - to name two of
Aspeli's works - the then new Portlets and Redirector don't bolster my
hope.

> of the learning curve until such time as Plone is simpler. (of course in
> reality Plone is a large system so can never be as easy to understand as
> grok, bfg or rails for instance).
I agree, and you get a lot for it, but we have to be careful that it
doesn't break under it's own weight.

Markus

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

Dylan Jay-4 () Re: A few suggestions

Reply Threaded

> -----Original Message-----
> From: Markus Bleicher [mailto:[hidden email]]
> Sent: Friday, 28 November 2008 6:21 AM
> Cc: [hidden email]
> Subject: Re: [Plone-docs] A few suggestions
>
> Dylan Jay wrote:
> >> -----Original Message-----
> >> From: Israel Saeta Pérez [mailto:[hidden email]]
> >> Sent: Thursday, 27 November 2008 10:18 AM
> >> To: [hidden email]
> >> Subject: Re: [Plone-docs] A few suggestions
> >>
> >> On Wed, Nov 26, 2008 at 9:07 PM, Markus Bleicher wrote:
> >>
> >>
> >> One thing I miss in this plone-docs mail storm is the idea that the
> >> problem is not about documentation, but about Plone/Zope itself.
> >> Maybe it is not about writing a how-to change the logo, but to make
> >> it
> >> simpler, get some information hiding in place, so you don't have to
> >> understand halve of the Zope/CMF/Plone stack to get it right. Which
> >> makes it hard to explain.
> >>
> >>
> >>
> >> I totally agree, but that's out of the documentation team's hands I
> guess.
> >
> > And I think it's in good hands. I was heartened by Martins talk at the
> > conference on simplifying Plone internals. I see our job as easing that
> pain
> I don't know his talk, but I hope that someone is moving something in
> that direction. My expirience makes me a little wary, though: I think
> everybody feels the pain handling this big intertwined thing, only that
> bolting on new stuff is more fun (and in a relatively mature and
> professional community like Plone's maybe more important: much more easy
> to sell) than cleaning up. The transition from CMF skins to Zope3 views,
> which added complexity but left all the old stuff in place (and was

I agree completely and have voiced this opinion many times in the past.

Perhaps we could float the idea of a "clean up Plone day". A sprint
dedicated to reimplementing old features in the new ways. Would be great for
people wanted to retrain in zope3.

> probably necessary, it has to go in that direction), or - to name two of
> Aspeli's works - the then new Portlets and Redirector don't bolster my
> hope.

One of the things he has admitted is some of own failings in hist tendency
to overengineer.

> > of the learning curve until such time as Plone is simpler. (of course in
> > reality Plone is a large system so can never be as easy to understand as
> > grok, bfg or rails for instance).
> I agree, and you get a lot for it, but we have to be careful that it
> doesn't break under it's own weight.

So any help in guiding this would be greatly appreciated.

> Markus
>
> -------------------------------------------------------------------------
> This SF.Net email is sponsored by the Moblin Your Move Developer's
> challenge
> Build the coolest Linux based applications with Moblin SDK & win great
> prizes
> Grand prize is a trip for two to an Open Source event anywhere in the
> world
> http://moblin-contest.org/redirect.php?banner_id=100&url=/
> _______________________________________________
> Plone-docs mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/plone-docs