December 2, 2008 - Editors Meeting
[Thanks Veda for taking minutes!]

Editors Present:
jluvsu2
anneb
dukebody
KurtB
MatthewWilkes
shurik
SteveM
vedawms
kamo1 (arrived during PLIP discussion)

Observing:
aclark
AdamAtNCPC
natea
KurtB


Following topics to be decided upon:
========================================

1) Will we split out "official docs" from "community" docs and drop permissions
on community docs to make contributing easier?
2) Will we go with Sphinx for developer documentation?
3) Will we move towards a manual-based system?
4) Will we get rid of PHC content types and just have the concept of a page, a
multipage document, and a reference manual? (This also implies moving toward
placeful content.)


1) Split of Official vs Community Docs:
-------------------------------------
For: vedawms, stevem, dukebody, matthewwilkes, shurik, anneb

Against: jluvsu2


1a) Mirroring Core vs Collective:
-----------------------------
For: vedawms, jluvsu2, anneb, dukebody, Matthew (if done in a branch and merged by an editor)

Against: none voiced


1b) Where do community docs go?
----------------------------
Possibly a different URL. What about wiki.plone.org?
All wiki-like docs in one place.
Would need commit rights.

Final decision: On plone.org, but not looking like official docs: SteveM, vedawms, jluvsu2, MatthewWilkes, dukebody, anneb


2) Sphinx:
--------
Clarify developer docs: several types
API docs
Manuals: developers won't write (SteveM)
MatthewWilkes: experiment with it more, wants caution; examples for people using plone shouldn't be there
Shurik: it won't work for general Plone docs


2a) API/module docs on sphinx, manuals on Plone:
---------------------------------------------
For:
SteveM, vedawms, jluvsu2, anneb

Not yet:
dukebody, MatthewWilkes

MatthewWilkes has concerns about quality of the docs.

Workload on editors: If we want to manage the instance, yes. Not necessarily an editor.

Final decision: Do a pilot. Limit the pilot to just API docs: SteveM, vedawms, MatthewWilkes, jluvsu2, dukebody, anneb

AnneB: leave the scope of the pilot up to the developers


3) Will we move towards a manual-based system?
----------------------------------------------

For: MatthewWilkes, vedawms, SteveM

What is a manual: Something that walks us thru, concept by concept; anne is tempted to leave tutorials out, but link to them

Prefers more modular docs that are linked or sorted in a way that builds onto one another: jluvsu2

jluvsu2 thinks bigger docs are harder to manage

Final decision: Manuals + quickstart, with the caveat that quickstart needs more thought: SteveM, vedawms, dukebody, anneb

Against: jluvsu2


3a) What is a quickstart?
-------------------------

anneb: quickstart is a contradiction in terms

dukebody: quickstart is by topic, not a quickstart in Plone itself

jluvsu2 thinks it's a "process overview"

dukebody: a tutorial format

jluvsu2: a quickstart is a tutorial, a slightly smaller manual

Hyperlink to a doc that touches more than one area from a quickstart

Final decision: manuals + quickstart



4) Simpler PHC types:
---------------------

vedawms: get rid of all special content types except multi-page docs like tutorials and manuals.

What about FAQs and glossary items? vedawms: Glossary items at the back of the manual, FAQs as pages elsewhere in the manual.

dukebody: manual == 'topic'

Glossary: anneb likes the idea, but others feel it is unusued (SteveM, vedawms, dukebody); integrating them into manuals could make them relevant - SteveM, vedawms

jluvsu2: depends on how the manuals are structured

SteveM: how-tos would be pages in manuals, +1 from jluvsu2, vedawms

Proposal: we keep multi-page docs like tutorials and manuals; FAQs and glossary items become part of a manual:

For: MatthewWilkes,  jluvsu2, SteveM, anneb, vedawms, dukebody

Against: none voiced

Abstaining: dukebody

Final decision: Organize by subject, not by content types; implementers will decide on the final details of how this gets implemented



QUESTIONS NOT FORMALLY POSED TO EDITORS MISSING FROM THE MEETING:
===================================================================


5) What About PLIPs:
------------------
Manpower is short, but if the info gets captured and we have the resources, we can use it.

Framework team decides.

For: vedawms, jluvsu2, kamo1, SteveM, dukebody, anneb

Against: none voiced

Final decision: Pending solicitation of missing editors



6) Commenting:
-------------
Kill commenting on all docs: jluvsu2, dukebody, SteveM, shurik, kamo1, anneb

Final decision: Pending solicitation of missing editors


7) Leadership:
-------------
SteveM proposes: Joanna for Managing Editor (cat herder in chief), SteveM for Janitor to provide policy leadership and take care of the facilities. Veda for UI design and to support Joanna.

For: anneb, kamo, dukebody, SteveM, jluvsu2, vedawms

Against: none voiced

Final decision: Pending solicitation of missing editors