Re: [Framework-Team] Re: Fwd: Including a Documentation section in each PLIP

[Israel Saeta Pérez]

On Sat, Nov 15, 2008 at 5:08 PM, Wichert Akkerman wrote:

> Previously Martin Aspeli wrote:
>> I do agree that documentation should be part of PLIPs. One simple thing
>> would be to just have a free-text on the PLIP that identifies the
>> documentation that is either required or extant for the PLIP, so that
>> people who look at the PLIP later can find a pointer to where there's
>> more documentation.
>
> I would much rather see the equivalent of the what-is-new-in-python-x.y
> documents: a thorough explanation of every change, its rationale, and
> the inpact that has on both existing and new code. That would then be a
> very useful starting point for the documentation team to update/extend
> other documentation.

If the documentation has to wait for version releases it will always
be behind code, which leads (among other causes) to the actual state
of some areas of the plone.org documentation: outdated. Of course the
documentation team has great responsibility here, but trying to keep
code as important as code will help.

IMO we should try to update at least the most general documentation
(manuals and important tutorials) before each release. To avoid
problems, we could start with 2 or 3 easy-to-document PLIPs and see if
we can manage to get relevant docs updated timely.

-- israel

@plone-docs: read the whole thread at http://is.gd/7DTi .

-------------------------------------------------------------------------
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

[Wichert Akkerman]

Previously Israel Saeta Pérez wrote:

> On Sat, Nov 15, 2008 at 5:08 PM, Wichert Akkerman wrote:
> > Previously Martin Aspeli wrote:
> >> I do agree that documentation should be part of PLIPs. One simple thing
> >> would be to just have a free-text on the PLIP that identifies the
> >> documentation that is either required or extant for the PLIP, so that
> >> people who look at the PLIP later can find a pointer to where there's
> >> more documentation.
> >
> > I would much rather see the equivalent of the what-is-new-in-python-x.y
> > documents: a thorough explanation of every change, its rationale, and
> > the inpact that has on both existing and new code. That would then be a
> > very useful starting point for the documentation team to update/extend
> > other documentation.
>
> If the documentation has to wait for version releases it will always
> be behind code, which leads (among other causes) to the actual state
> of some areas of the plone.org documentation: outdated. Of course the
> documentation team has great responsibility here, but trying to keep
> code as important as code will help.

You misunderstood my point. What I want to see is for each PLIP to have
the equivalent of a section of the what-is-new-in-python-x.y documents.
That does not require waiting for a release.

Wichert.

--
Wichert Akkerman <[hidden email]>    It is simple to make things.
http://www.wiggy.net/                   It is hard to make things simple.

-------------------------------------------------------------------------
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]

On Sat, Nov 15, 2008 at 6:01 PM, Wichert Akkerman wrote:

>> > I would much rather see the equivalent of the what-is-new-in-python-x.y
>> > documents: a thorough explanation of every change, its rationale, and
>> > the inpact that has on both existing and new code. That would then be a
>> > very useful starting point for the documentation team to update/extend
>> > other documentation.
>>
> Israel Saeta wrote:
>> If the documentation has to wait for version releases it will always
>> be behind code, which leads (among other causes) to the actual state
>> of some areas of the plone.org documentation: outdated. Of course the
>> documentation team has great responsibility here, but trying to keep
>> code as important as code will help.

Wichert Akkerman wrote:
> You misunderstood my point. What I want to see is for each PLIP to have
> the equivalent of a section of the what-is-new-in-python-x.y documents.
> That does not require waiting for a release.

Uh yes you're right I've misunderstood you, my apologies. Maybe I'm
behaving in a bit too defensive way here, sorry.

I would be ok with any text explaining the impact of the PLIP in the
way we develop with, customize, or manage Plone. Links to existing
documentation that would become obsolete could be optional.

Some trivial examples:

- http://plone.org/products/plone/roadmap/238
Inline editing will be disabled by default. Update User Manual
http://is.gd/7El5 .

- http://plone.org/products/plone/roadmap/223
Theming resources based on base_properties.props will become
deprecated in favour of zrt resources.

-- Israel

-------------------------------------------------------------------------
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]

Hello doc team,

The proposal of describing the documentation impact of each PLIP was recently discussed in the framework-team list. See this thread.

They liked the idea overall, but the conversation ended discussing what should this documentation lines include to avoid raising the PLIP submission barrier too high. What would this PLIP change and how? Some example links to existing documentation that would become outdated?

What would work/be enough for you? I'd love to make a decision and commit to it in the next documentation editor's meeting.

-- israel

-------------------------------------------------------------------------
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]

Some javascript/style in this post has been disabled (why?)

I agree with martin that its too hard to find relevant documentation to change at the moment.

 

I think the quicker we can come to a system that is easier for core developers to find and alter documentation the better. At that time we should adding it to the PLIP would be great.

 

Dylan Jay
Technical Solutions Manager, PretaWeb.com
---
M:[phone] ~ MSN:[hidden email] ~ Y!+Skype:dylan_jay ~ ICQ:520341

---

From: Israel Saeta Pérez [mailto:[hidden email]]
Sent: Sunday, 30 November 2008 9:01 PM
To: Plone Docs List
Subject: Re: [Plone-docs] [Framework-Team] Re: Fwd: Including aDocumentation section in each PLIP

 

Hello doc team,

The proposal of describing the documentation impact of each PLIP was recently discussed in the framework-team list. See this thread.

They liked the idea overall, but the conversation ended discussing what should this documentation lines include to avoid raising the PLIP submission barrier too high. What would this PLIP change and how? Some example links to existing documentation that would become outdated?

What would work/be enough for you? I'd love to make a decision and commit to it in the next documentation editor's meeting.

-- israel

-------------------------------------------------------------------------
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

[JoAnna Springsteen]

> What would work/be enough for you? I'd love to make a decision and commit to
> it in the next documentation editor's meeting.
>

It would be handy if specific docs could be linked to from the PLIP so
we know which docs need to be updated. Searching for them may or may
not be tricky, depending how well you know the doc set. *shrugs*
Mostly it just takes a little time. Some people may not be willing to
invest that time when submitting a PLIP. But that makes me wonder if a
PLIP is really taking the bigger picture into consideration if the
person filling it out doesn't care to worry about docs it may affect.
A PLIP may be a good idea but if we don't look at the bigger picture
and see how it fits, how do we know if it's something we should
include? Is it too much to ask that the person submitting the PLIP
expands their view of the bigger picture to include docs as well? Does
it really set the submission bar too high? I honestly don't know. I
suspect that's something the Framework team needs to think about.

Biggest thing that would need to happen is have devs/framework team
work more closely together.

It's easy to update docs when we have a list of features/PLIPs. Once
the doc team has that list, we can comb through the docs and pick out
which ones need to be updated. It worked fairly nicely for us when we
updated docs for the Plone 3 release. Having that is enough for us to
get by. But I'd like to see us update docs every time the
functionality is changed. I'd really love to see everything documented
as it's developed. And by documented, I don't just mean comments in
the code. I'd love to see API, how tos/tutorials/manuals, doc
tests/user stories, and anything else that might help us. (Yes, I am
an idealist, but hey if we're talking wish list here, why not.)

This is a really tough call. Right now we don't have enough people
actively volunteering and doing work on the doc team to handle this on
our own. The success of this idea, like many others, depends on people
getting in there and getting it done. Even if the editorial team
agrees to try and take this on, that doesn't guarantee us man power to
do it.

-------------------------------------------------------------------------
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]

Hi,

My impression from the thread was the framework team aren't resisting
because they don't value documentation. They are resisting because the PHC
soup is too hard to "know well".

I think putting the responsibility back on the doc team or editors isn't the
answer. Even if we did have more people, editors can't possibly know the
implications of the code changes as well as those developing the new code.

If the docset is too hard to know then our job is to make it easy to know
and easy to change.
- Reduce the corpus down to a manageable size by splitting "official" from
community docs. Official being the only part PLIPS would require changing.
- Giving it a good table of contents so its very obvious which parts have
changed. PLIPs could reference chapters and sections.
- Removing all overlap so less needs to be changed. One place for everything
and everything in its place.
- Let developers easily integrate their existing module documentation if
appropriate in order to ease their load.
- the entire official docset appears multiple times on Plone.org, once for
each release and another for the upcoming (HEAD) version, so an author
doesn't have to consider old Plone versions in the writing itself.

Anything else we can do to make it easier for them?


Dylan Jay
Technical Solutions Manager, PretaWeb.com
---
M:[phone] ~ MSN:[hidden email] ~ Y!+Skype:dylan_jay ~ ICQ:520341

> -----Original Message-----
> From: JoAnna Springsteen [mailto:[hidden email]]
> Sent: Monday, 1 December 2008 4:19 PM
> To: Israel Saeta Pérez
> Cc: Plone Docs List
> Subject: Re: [Plone-docs] [Framework-Team] Re: Fwd: Including
> aDocumentation section in each PLIP
>
> > What would work/be enough for you? I'd love to make a decision and
> commit to
> > it in the next documentation editor's meeting.
> >
>
> It would be handy if specific docs could be linked to from the PLIP so
> we know which docs need to be updated. Searching for them may or may
> not be tricky, depending how well you know the doc set. *shrugs*
> Mostly it just takes a little time. Some people may not be willing to
> invest that time when submitting a PLIP. But that makes me wonder if a
> PLIP is really taking the bigger picture into consideration if the
> person filling it out doesn't care to worry about docs it may affect.
> A PLIP may be a good idea but if we don't look at the bigger picture
> and see how it fits, how do we know if it's something we should
> include? Is it too much to ask that the person submitting the PLIP
> expands their view of the bigger picture to include docs as well? Does
> it really set the submission bar too high? I honestly don't know. I
> suspect that's something the Framework team needs to think about.
>
> Biggest thing that would need to happen is have devs/framework team
> work more closely together.
>
> It's easy to update docs when we have a list of features/PLIPs. Once
> the doc team has that list, we can comb through the docs and pick out
> which ones need to be updated. It worked fairly nicely for us when we
> updated docs for the Plone 3 release. Having that is enough for us to
> get by. But I'd like to see us update docs every time the
> functionality is changed. I'd really love to see everything documented
> as it's developed. And by documented, I don't just mean comments in
> the code. I'd love to see API, how tos/tutorials/manuals, doc
> tests/user stories, and anything else that might help us. (Yes, I am
> an idealist, but hey if we're talking wish list here, why not.)
>
> This is a really tough call. Right now we don't have enough people
> actively volunteering and doing work on the doc team to handle this on
> our own. The success of this idea, like many others, depends on people
> getting in there and getting it done. Even if the editorial team
> agrees to try and take this on, that doesn't guarantee us man power to
> do it.
>
> -------------------------------------------------------------------------
> 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

[Wichert Akkerman]

Previously Dylan Jay wrote:
> Hi,
>
> My impression from the thread was the framework team aren't resisting
> because they don't value documentation. They are resisting because the PHC
> soup is too hard to "know well".

I don't think there's been any discussion on it actually. But indeed, I
do not think it is reasonably to ask PLIP implementers to find all
relevant entries in PHC.

What I want from PLIP implementers is the following:

- a description of what changes for developers (ie new patterns to use)
- a description of what changes for users (ie new patterns to use)
- proper documentation for new features.

All or none of those may be doctests, as long as they are readable
documentation, not tests with some narrative in between code snippets.

That should give the documentation more than enough data to find and
update documetation on plone.org

Wichert.

--
Wichert Akkerman <[hidden email]>    It is simple to make things.
http://www.wiggy.net/                   It is hard to make things simple.

-------------------------------------------------------------------------
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]

> -----Original Message-----
> From: Wichert Akkerman [mailto:[hidden email]] On Behalf Of
> Wichert Akkerman
> Sent: Tuesday, 2 December 2008 5:49 AM
> To: Dylan Jay
> Cc: 'JoAnna Springsteen'; 'Israel Saeta Pérez'; 'Plone Docs List'
> Subject: Re: [Plone-docs] [Framework-Team] Re: Fwd: Including
> aDocumentation section in each PLIP
>
> Previously Dylan Jay wrote:
> > Hi,
> >
> > My impression from the thread was the framework team aren't resisting
> > because they don't value documentation. They are resisting because the
> PHC
> > soup is too hard to "know well".
>
> I don't think there's been any discussion on it actually. But indeed, I
> do not think it is reasonably to ask PLIP implementers to find all
> relevant entries in PHC.

That was my take on the framework team discussion. That developers updating
the actual Plone.org documentation is too hard and even linking to the docs
which should be updated is pretty hard.
 

> What I want from PLIP implementers is the following:
>
> - a description of what changes for developers (ie new patterns to use)
> - a description of what changes for users (ie new patterns to use)
> - proper documentation for new features.
>
> All or none of those may be doctests, as long as they are readable
> documentation, not tests with some narrative in between code snippets.
>
> That should give the documentation more than enough data to find and
> update documetation on plone.org

I think this would be a great improvement but this means it’s the doc teams
job to update the documentation which I think is what is currently broken in
this process and will result in an overloaded doc team and docs not done.

Why not go one further and say if the developer is changing the api by
creating or changing core modules its also their job to directly alter the
api/developer documentation. User documentation is still probably better
done by the doc team.
If the documentation is unintegrated then its likely to stay that way.

Imagine a new PLIP process like the following:-

1) PLIP created which includes references to sections of the Plone dev
manual that will change and users manual changes
2) implements changes in a module, including some doctest style
documentation
3) checks out collective.sphinx.plonedocs and creates a branch for their
PLIP.
4) edits rst files in plonedocs such that it now links in their new module
and its documentation and also changes any other parts that are outdated by
this change. The result is a single consistent readable manual.
5) using buildout compliles the documentation so it can be read.
6) submits the plip for review which now includes a reference to the
plonedocs branch.
6.5) doc team editor is now part of the PLIP review process and reviews the
developer documentation changes to see if they are acceptable
7) if accepted the plonedocs PLIP branch is merge into the trunk and then
the resulting manual uploaded into Plone.org as the bleeding edge upcoming
Plone release manual.
8) doc team go and update the user documentation in the Plone manual based
on the guidelines in the PLIP
9) at the time of the next Plone release the sphinx.plonedocs gets tagged
and version pinned and the Plone.org upcoming manual becomes
Plone.org/dev/manual/3.3 and a new upcoming manual started. Same for the
user manual.


That’s really cool process I think. If you are changing the Plone core, you
are changing the Plone core docs and both get reviewed together.
It's not too onerous is it?




> Wichert.
>
> --
> Wichert Akkerman <[hidden email]>    It is simple to make things.
> http://www.wiggy.net/                   It is hard to make things simple.


-------------------------------------------------------------------------
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

[Wichert Akkerman]

Some javascript/style in this post has been disabled (why?)

On 12/2/08 12:42 AM, Dylan Jay wrote:

-----Original Message-----
From: Wichert Akkerman [[hidden email]] On Behalf Of
Wichert Akkerman
Sent: Tuesday, 2 December 2008 5:49 AM
To: Dylan Jay
Cc: 'JoAnna Springsteen'; 'Israel Saeta Pérez'; 'Plone Docs List'
Subject: Re: [Plone-docs] [Framework-Team] Re: Fwd: Including
aDocumentation section in each PLIP

Previously Dylan Jay wrote:
    

Hi,

My impression from the thread was the framework team aren't resisting
because they don't value documentation. They are resisting because the
      

PHC
    

soup is too hard to "know well".
      

I don't think there's been any discussion on it actually. But indeed, I
do not think it is reasonably to ask PLIP implementers to find all
relevant entries in PHC.
    

That was my take on the framework team discussion. That developers updating
the actual Plone.org documentation is too hard and even linking to the docs
which should be updated is pretty hard.
 
  

What I want from PLIP implementers is the following:

- a description of what changes for developers (ie new patterns to use)
- a description of what changes for users (ie new patterns to use)
- proper documentation for new features.

All or none of those may be doctests, as long as they are readable
documentation, not tests with some narrative in between code snippets.

That should give the documentation more than enough data to find and
update documetation on plone.org
    

I think this would be a great improvement but this means it’s the doc teams
job to update the documentation which I think is what is currently broken in
this process and will result in an overloaded doc team and docs not done.

Why not go one further and say if the developer is changing the api by
creating or changing core modules its also their job to directly alter the
api/developer documentation. User documentation is still probably better
done by the doc team. 
  

I do not think we can require that until that API documentation is managed in a developer-friendly way. For me as developer that means preferable inside the package(s) itself, but definitely in a svn-managed location in restructured text format. If you force me to edit webpages using kupu I will most likely never get around to it.

6.5) doc team editor is now part of the PLIP review process and reviews the
developer documentation changes to see if they are acceptable
  

The review process has no special roles. If the doc team wants someone to be part of the review process they will have to volunteer to be a member of the framework team, just like we have Danny doing user interface review as part of the framework team.

Wichert.


-------------------------------------------------------------------------
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