Editor Team Meeting Summary

[JoAnna Springsteen]

As you may know, the Editorial Team met on Tuesday to make decisions
on some of the hot topics that have been debated on the doc list.
We met for an hour and a half, discussed many of the issues at length
and came to the following decisions:

- We will split official and community docs into separate sections. We
will do this using a similar model as the collective vs. core.
Community docs will stay on plone.org but will be visually
distinguishable from official docs. Implementation of this is to be
decided.

- We will do a pilot of Sphinx for API documentation only. We would
like someone to step up and manage Sphinx and the process.
Implementation details are still to be worked out. The editor team
will work with who ever wants to manage the Sphinx implementation in
order to get it up and worked. (ie: find some space for it, etc)

- Official documents will move towards a more manual-based system. We
will also have quick starts (or process overviews) for each topic.
Implementation depends directly on PHC changes.

- We're going to make some changes to PHC itself. We will organize
documents by topic instead of content types. We will still use
multi-page content types like manuals and tutorials but the rest will
probably be just plain old pages. Steve M will take charge of leading
these changes and work with a team to decide details. [and they're
starting this weekend!]

- Israel proposed that documentation be included when a PLIP is
proposed. The editorial team decided to leave the final decision up to
the Framework team. If the proposal is accepted, the editorial team
will work with the framework team and the rest of the doc team to
support. It should be noted we are short on resources and we will need
help if implemented.

- We are getting rid of commenting on all official docs.

- Steve M proposed and nominated several people to be the official
leaders of the Doc team. Veda Williams will be in charge of design and
presentation concerns, Steve McMahon will be in charge of policies and
take care of facilities (ie: PHC, groups, etc) and be our direct link
to the board, and JoAnna Springsteen will be Managing Editor (aka: Cat
Herder in Chief).


You can see the full meeting notes and a transcript of the discussion here:
http://www.openplans.org/projects/plone-documentation/12-2-2008

------------------------------------------------------------------------------
SF.Net email is Sponsored by MIX09, March 18-20, 2009 in Las Vegas, Nevada.
The future of the web can't happen without you.  Join us at MIX09 to help
pave the way to the Next Web now. Learn more and register at
http://ad.doubleclick.net/clk;208669438;13503038;i?http://2009.visitmix.com/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[Dylan Jay-4]

> -----Original Message-----
> From: JoAnna Springsteen [mailto:[hidden email]]
> Sent: Saturday, 6 December 2008 10:16 AM
> To: Plone Docs List; Plone Documentation Team, Editorial Board
> Subject: [Plone-docs] Editor Team Meeting Summary
>
> As you may know, the Editorial Team met on Tuesday to make decisions
> on some of the hot topics that have been debated on the doc list.
> We met for an hour and a half, discussed many of the issues at length
> and came to the following decisions:
>
> - We will split official and community docs into separate sections. We
> will do this using a similar model as the collective vs. core.
> Community docs will stay on plone.org but will be visually
> distinguishable from official docs. Implementation of this is to be
> decided.
>
> - We will do a pilot of Sphinx for API documentation only. We would
> like someone to step up and manage Sphinx and the process.
> Implementation details are still to be worked out. The editor team
> will work with who ever wants to manage the Sphinx implementation in
> order to get it up and worked. (ie: find some space for it, etc)

I'm happy to step up and do that. I have a good feel for how sphinx could
work for such a pilot, how it could integrate with the existing Plone docs.
I have a good working relationship with Rok Garbas whose done most of the
work so far and would love to work with anyone else who would like to make
plones application programming interface clear and easy to understand.
 
> - Official documents will move towards a more manual-based system. We
> will also have quick starts (or process overviews) for each topic.
> Implementation depends directly on PHC changes.

Thank you for all your efforts in making this happen. I again apologise if
during this debate I have upset anyone. I think we arrived at the right
compromise at the end of the day.

> - We're going to make some changes to PHC itself. We will organize
> documents by topic instead of content types. We will still use
> multi-page content types like manuals and tutorials but the rest will
> probably be just plain old pages. Steve M will take charge of leading
> these changes and work with a team to decide details. [and they're
> starting this weekend!]
>
> - Israel proposed that documentation be included when a PLIP is
> proposed. The editorial team decided to leave the final decision up to
> the Framework team. If the proposal is accepted, the editorial team
> will work with the framework team and the rest of the doc team to
> support. It should be noted we are short on resources and we will need
> help if implemented.
>
> - We are getting rid of commenting on all official docs.
>
> - Steve M proposed and nominated several people to be the official
> leaders of the Doc team. Veda Williams will be in charge of design and
> presentation concerns, Steve McMahon will be in charge of policies and
> take care of facilities (ie: PHC, groups, etc) and be our direct link
> to the board, and JoAnna Springsteen will be Managing Editor (aka: Cat
> Herder in Chief).
>
>
> You can see the full meeting notes and a transcript of the discussion
> here:
> http://www.openplans.org/projects/plone-documentation/12-2-2008
>
> --------------------------------------------------------------------------
> ----
> SF.Net email is Sponsored by MIX09, March 18-20, 2009 in Las Vegas,
> Nevada.
> The future of the web can't happen without you.  Join us at MIX09 to help
> pave the way to the Next Web now. Learn more and register at
> http://ad.doubleclick.net/clk;208669438;13503038;i?http://2009.visitmix.co
> m/
> _______________________________________________
> Plone-docs mailing list
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/plone-docs

------------------------------------------------------------------------------
SF.Net email is Sponsored by MIX09, March 18-20, 2009 in Las Vegas, Nevada.
The future of the web can't happen without you.  Join us at MIX09 to help
pave the way to the Next Web now. Learn more and register at
http://ad.doubleclick.net/clk;208669438;13503038;i?http://2009.visitmix.com/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs

[JoAnna Springsteen]

> I'm happy to step up and do that. I have a good feel for how sphinx could
> work for such a pilot, how it could integrate with the existing Plone docs.
> I have a good working relationship with Rok Garbas whose done most of the
> work so far and would love to work with anyone else who would like to make
> plones application programming interface clear and easy to understand.

We will add your name to the list of potential people.
In the mean time, the editorial team needs to hash out a list of what
we expect from this pilot, some guidelines, and the general mechanics
of where we are going to put the API docs.
Please note that we have only approved this pilot for API docs only.
No other docs from plone.org will be going into sphinx.

Since our main focus right now is preparing for plone.org to move to
plone 3, we will probably not get to this until early January. So sit
tight for a few weeks and if anyone else is interested in working on
this project, please contact the editorial team (specifically me
please).

Lots of changes coming in the months ahead and we're going to need all
kinds of volunteers!

J.

------------------------------------------------------------------------------
SF.Net email is Sponsored by MIX09, March 18-20, 2009 in Las Vegas, Nevada.
The future of the web can't happen without you.  Join us at MIX09 to help
pave the way to the Next Web now. Learn more and register at
http://ad.doubleclick.net/clk;208669438;13503038;i?http://2009.visitmix.com/
_______________________________________________
Plone-docs mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/plone-docs