Plone

›

Documentation Team

Re: Sphinx for Plone doc ?

9 Messages

Martin Aspeli-2

Reply Threaded

Hi Dylan,

> I think a key difference is that IMO PHC promotes lots of versions of
> documentation. Each tutorial is an island created by one person at one
> time.

True, but likely so is a file in svn. :)

> I'm not sure how sphinx works but the end result looks more like a
> cohesive explanation of how stuff works and fits togeather. What is
> their update process?

Sphinx just generates HTML from reST files associated with packages.
That's why it works well for developer/low-level documentation. I write
readme's and doctests for my packages, and Sphinx makes them accessible
in a nice way.

> Hopefully the missing piece for PHC is editors to make the individual
> submissions into a whole.

Right. The current documentation isn't suffering from a technology
problem, it's suffering (less than it used to, it must be said) from the
all too familiar problem that to a lot of people, writing documentation
is not as fun as writing code, and updating and editing documentation is
even more onerous.

For example, I doubt we'd get Laura or JoAnna or Donna to write
documentation in reST in svn. Not because they couldn't, but because
that kind of environment isn't geared for that type of user or that type
of documentation. Even figuring out where to put it would be awkward.
reST is awkward. Lack of WYSIWYG is awkward.

And by the same token, we won't necessarily get Kapil or Hanno or Sidnei
to write documentation for their packages in the PHC, although they do
often write excellent developer documentation that's embedded with the
code. Sphinx could let us make that more accessible to people. I don't
think it'll solve any other problems for us.

> Certainly doing what they have done and having versions of their docs
> linked to teh products version is the way to go I think.

Yep.

Martin

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

-------------------------------------------------------------------------
Sponsored by: SourceForge.net Community Choice Awards: VOTE NOW!
Studies have shown that voting for your favorite open source project,
along with a healthy diet, reduces your potential for chronic lameness
and boredom. Vote Now at http://www.sourceforge.net/community/cca08
_______________________________________________
Plone-docs mailing list
Plone-docs@...
https://lists.sourceforge.net/lists/listinfo/plone-docs

Dylan Jay-3

Re: Sphinx for Plone doc ?

Reply Threaded

I didn't make myself very clear.

Absolutely agree that a CMS is the most accessible way to help people
make documentation.
One thing that api docs do is show 1 document per part of the system,
all togeather for a single version. http://www.python.org/doc/versions/
Hopefully thats something that editors can do with the PHC. Create one
up to date consistent version of the docs for the current version, and
relegate old docs to old versions so its clear they are obsolete.

Martin Aspeli wrote:

> Hi Dylan,
>
>> I think a key difference is that IMO PHC promotes lots of versions of
>> documentation. Each tutorial is an island created by one person at one
>> time.
>
> True, but likely so is a file in svn. :)
>
>> I'm not sure how sphinx works but the end result looks more like a
>> cohesive explanation of how stuff works and fits togeather. What is
>> their update process?
>
> Sphinx just generates HTML from reST files associated with packages.
> That's why it works well for developer/low-level documentation. I write
> readme's and doctests for my packages, and Sphinx makes them accessible
> in a nice way.
>
>> Hopefully the missing piece for PHC is editors to make the individual
>> submissions into a whole.
>
> Right. The current documentation isn't suffering from a technology
> problem, it's suffering (less than it used to, it must be said) from the
> all too familiar problem that to a lot of people, writing documentation
> is not as fun as writing code, and updating and editing documentation is
> even more onerous.
>
> For example, I doubt we'd get Laura or JoAnna or Donna to write
> documentation in reST in svn. Not because they couldn't, but because
> that kind of environment isn't geared for that type of user or that type
> of documentation. Even figuring out where to put it would be awkward.
> reST is awkward. Lack of WYSIWYG is awkward.
>
> And by the same token, we won't necessarily get Kapil or Hanno or Sidnei
> to write documentation for their packages in the PHC, although they do
> often write excellent developer documentation that's embedded with the
> code. Sphinx could let us make that more accessible to people. I don't
> think it'll solve any other problems for us.
>
>> Certainly doing what they have done and having versions of their docs
>> linked to teh products version is the way to go I think.
>
> Yep.
>
> Martin
>
>

-------------------------------------------------------------------------
Sponsored by: SourceForge.net Community Choice Awards: VOTE NOW!
Studies have shown that voting for your favorite open source project,
along with a healthy diet, reduces your potential for chronic lameness
and boredom. Vote Now at http://www.sourceforge.net/community/cca08
_______________________________________________
Plone-docs mailing list
Plone-docs@...
https://lists.sourceforge.net/lists/listinfo/plone-docs

Wichert Akkerman

Re: Sphinx for Plone doc ?

Reply Threaded

Previously Dylan Jay wrote:

> Martin Aspeli wrote:
> > Hi Dylan,
> >
> >> I think a key difference is that IMO PHC promotes lots of versions of
> >> documentation. Each tutorial is an island created by one person at one
> >> time.
> >
> > True, but likely so is a file in svn. :)
> >
> >> I'm not sure how sphinx works but the end result looks more like a
> >> cohesive explanation of how stuff works and fits togeather. What is
> >> their update process?
> >
> > Sphinx just generates HTML from reST files associated with packages.
> > That's why it works well for developer/low-level documentation. I write
> > readme's and doctests for my packages, and Sphinx makes them accessible
> > in a nice way.
> >
> >> Hopefully the missing piece for PHC is editors to make the individual
> >> submissions into a whole.
> >
> > Right. The current documentation isn't suffering from a technology
> > problem, it's suffering (less than it used to, it must be said) from the
> > all too familiar problem that to a lot of people, writing documentation
> > is not as fun as writing code, and updating and editing documentation is
> > even more onerous.
> >
> > For example, I doubt we'd get Laura or JoAnna or Donna to write
> > documentation in reST in svn. Not because they couldn't, but because
> > that kind of environment isn't geared for that type of user or that type
> > of documentation. Even figuring out where to put it would be awkward.
> > reST is awkward. Lack of WYSIWYG is awkward.
> >
> > And by the same token, we won't necessarily get Kapil or Hanno or Sidnei
> > to write documentation for their packages in the PHC, although they do
> > often write excellent developer documentation that's embedded with the
> > code. Sphinx could let us make that more accessible to people. I don't
> > think it'll solve any other problems for us.

Which immediately makes me conclude that Sphinx would be ideal to build
reference documentation (which do don't have at all right now) while PHC
is great for other types of documentation.

Developers need to do a much better job of writing reference
documentation for the code they write.
http://pypi.python.org/pypi/plone.portlets is useless for example, while
http://pypi.python.org/pypi/plone.session is somewhat useful. If I can
get away with it I'm tempted to make it a hard requirement for
everything that gets merged for Plone 4.

Wichert.

--
Wichert Akkerman <wichert@...> It is simple to make things.
http://www.wiggy.net/ It is hard to make things simple.

-------------------------------------------------------------------------
Sponsored by: SourceForge.net Community Choice Awards: VOTE NOW!
Studies have shown that voting for your favorite open source project,
along with a healthy diet, reduces your potential for chronic lameness
and boredom. Vote Now at http://www.sourceforge.net/community/cca08
_______________________________________________
Plone-docs mailing list
Plone-docs@...
https://lists.sourceforge.net/lists/listinfo/plone-docs

Martin Aspeli-2

Re: Sphinx for Plone doc ?

Reply Threaded

Wichert Akkerman wrote:

> Previously Dylan Jay wrote:
>> Martin Aspeli wrote:
>>> Hi Dylan,
>>>
>>>> I think a key difference is that IMO PHC promotes lots of versions of
>>>> documentation. Each tutorial is an island created by one person at one
>>>> time.
>>> True, but likely so is a file in svn. :)
>>>
>>>> I'm not sure how sphinx works but the end result looks more like a
>>>> cohesive explanation of how stuff works and fits togeather. What is
>>>> their update process?
>>> Sphinx just generates HTML from reST files associated with packages.
>>> That's why it works well for developer/low-level documentation. I write
>>> readme's and doctests for my packages, and Sphinx makes them accessible
>>> in a nice way.
>>>
>>>> Hopefully the missing piece for PHC is editors to make the individual
>>>> submissions into a whole.
>>> Right. The current documentation isn't suffering from a technology
>>> problem, it's suffering (less than it used to, it must be said) from the
>>> all too familiar problem that to a lot of people, writing documentation
>>> is not as fun as writing code, and updating and editing documentation is
>>> even more onerous.
>>>
>>> For example, I doubt we'd get Laura or JoAnna or Donna to write
>>> documentation in reST in svn. Not because they couldn't, but because
>>> that kind of environment isn't geared for that type of user or that type
>>> of documentation. Even figuring out where to put it would be awkward.
>>> reST is awkward. Lack of WYSIWYG is awkward.
>>>
>>> And by the same token, we won't necessarily get Kapil or Hanno or Sidnei
>>> to write documentation for their packages in the PHC, although they do
>>> often write excellent developer documentation that's embedded with the
>>> code. Sphinx could let us make that more accessible to people. I don't
>>> think it'll solve any other problems for us.
>
> Which immediately makes me conclude that Sphinx would be ideal to build
> reference documentation (which do don't have at all right now) while PHC
> is great for other types of documentation.
>
> Developers need to do a much better job of writing reference
> documentation for the code they write.
> http://pypi.python.org/pypi/plone.portlets is useless for example, while
> http://pypi.python.org/pypi/plone.session is somewhat useful. If I can
> get away with it I'm tempted to make it a hard requirement for
> everything that gets merged for Plone 4.

Heh, point taken. If I put the plone.portlets doctest into pypi, you may
be a bit scared, though. ;-)

I think making this a requirement for new packages is a good idea, so
long as we don't become overly draconian about it.

Martin

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

-------------------------------------------------------------------------
Sponsored by: SourceForge.net Community Choice Awards: VOTE NOW!
Studies have shown that voting for your favorite open source project,
along with a healthy diet, reduces your potential for chronic lameness
and boredom. Vote Now at http://www.sourceforge.net/community/cca08
_______________________________________________
Plone-docs mailing list
Plone-docs@...
https://lists.sourceforge.net/lists/listinfo/plone-docs

JoAnna Springsteen

Re: Sphinx for Plone doc ?

Reply Threaded

>
>>>
>>>
>>>
>>>
>>>
> Which immediately makes me conclude that Sphinx would be ideal to
> build
> reference documentation (which do don't have at all right now) while
> PHC
> is great for other types of documentation.
>
> Developers need to do a much better job of writing reference
> documentation for the code they write.
> http://pypi.python.org/pypi/plone.portlets is useless for example,
> while
> http://pypi.python.org/pypi/plone.session is somewhat useful. If I can
> get away with it I'm tempted to make it a hard requirement for
> everything that gets merged for Plone 4.

Hmmm. Getting developers to write more reference docs.... Sounds like
a good conference disscussion to me. If you guys think it's worth a
conf talk, I'll organize a panel talk if people agree to be on the
panel. Might get us some good ideas and a way to move forward. While
you're right that most of the doc team wouldnt use reST, anything that
gets devs documenting is worth a shot in my book.

-------------------------------------------------------------------------
Sponsored by: SourceForge.net Community Choice Awards: VOTE NOW!
Studies have shown that voting for your favorite open source project,
along with a healthy diet, reduces your potential for chronic lameness
and boredom. Vote Now at http://www.sourceforge.net/community/cca08
_______________________________________________
Plone-docs mailing list
Plone-docs@...
https://lists.sourceforge.net/lists/listinfo/plone-docs

Wichert Akkerman

Re: Sphinx for Plone doc ?

Reply Threaded

Previously Martin Aspeli wrote:

> Wichert Akkerman wrote:
> > Previously Dylan Jay wrote:
> >> Martin Aspeli wrote:
> >>> Hi Dylan,
> >>>
> >>>> I think a key difference is that IMO PHC promotes lots of versions of
> >>>> documentation. Each tutorial is an island created by one person at one
> >>>> time.
> >>> True, but likely so is a file in svn. :)
> >>>
> >>>> I'm not sure how sphinx works but the end result looks more like a
> >>>> cohesive explanation of how stuff works and fits togeather. What is
> >>>> their update process?
> >>> Sphinx just generates HTML from reST files associated with packages.
> >>> That's why it works well for developer/low-level documentation. I write
> >>> readme's and doctests for my packages, and Sphinx makes them accessible
> >>> in a nice way.
> >>>
> >>>> Hopefully the missing piece for PHC is editors to make the individual
> >>>> submissions into a whole.
> >>> Right. The current documentation isn't suffering from a technology
> >>> problem, it's suffering (less than it used to, it must be said) from the
> >>> all too familiar problem that to a lot of people, writing documentation
> >>> is not as fun as writing code, and updating and editing documentation is
> >>> even more onerous.
> >>>
> >>> For example, I doubt we'd get Laura or JoAnna or Donna to write
> >>> documentation in reST in svn. Not because they couldn't, but because
> >>> that kind of environment isn't geared for that type of user or that type
> >>> of documentation. Even figuring out where to put it would be awkward.
> >>> reST is awkward. Lack of WYSIWYG is awkward.
> >>>
> >>> And by the same token, we won't necessarily get Kapil or Hanno or Sidnei
> >>> to write documentation for their packages in the PHC, although they do
> >>> often write excellent developer documentation that's embedded with the
> >>> code. Sphinx could let us make that more accessible to people. I don't
> >>> think it'll solve any other problems for us.
> >
> > Which immediately makes me conclude that Sphinx would be ideal to build
> > reference documentation (which do don't have at all right now) while PHC
> > is great for other types of documentation.
> >
> > Developers need to do a much better job of writing reference
> > documentation for the code they write.
> > http://pypi.python.org/pypi/plone.portlets is useless for example, while
> > http://pypi.python.org/pypi/plone.session is somewhat useful. If I can
> > get away with it I'm tempted to make it a hard requirement for
> > everything that gets merged for Plone 4.
>
> Heh, point taken. If I put the plone.portlets doctest into pypi, you may
> be a bit scared, though. ;-)

A doctest is a test, it is often not very useful as user documentation
or reference documentation but more a document describing implementation
details and corner case. Still, it's a hell of a lot better than nothing
at all :)

Wichert.

--
Wichert Akkerman <wichert@...> It is simple to make things.
http://www.wiggy.net/ It is hard to make things simple.

-------------------------------------------------------------------------
Sponsored by: SourceForge.net Community Choice Awards: VOTE NOW!
Studies have shown that voting for your favorite open source project,
along with a healthy diet, reduces your potential for chronic lameness
and boredom. Vote Now at http://www.sourceforge.net/community/cca08
_______________________________________________
Plone-docs mailing list
Plone-docs@...
https://lists.sourceforge.net/lists/listinfo/plone-docs

Dylan Jay-3

Re: Sphinx for Plone doc ?

Reply Threaded

Wichert Akkerman wrote:

I'd like to see a consistent set of PHC docs combined with api type
reference docs from the code in such a way that they were released in
conjunction with plone releases (of course there might have to be a lag)

e.g. The plone 3.1 docs. The plone 3.0 docs. The plone 3.5 docs.

That might mean for each release the editors of each PHC section
selecting a subset of the tutorials etc that togeather make an
up-to-date and *consistent* set of documentation to represent that
release. Its all tagged and is then available at a url that indicates
which release it belongs to.

What I mean by consistent is tutorials/howtos etc that don't contradict
each other or make confusingly different suggestions on the approach to
solve problems.

Technically how this happens I don't know since I seem to be suggesting
that PHC items are copied and then archived for each release, or perhaps
using iterate. and also that api docs prob have to be brought into PHC
to participate in that same versioning process.

or perhaps its easier if PHC content is versioned into svn along with
the api docs and then all published statically. But then you'd need
links back to plone docs comments and the "live" plone docs for
encouraging new doc submissions.

Dylan.

-------------------------------------------------------------------------
Sponsored by: SourceForge.net Community Choice Awards: VOTE NOW!
Studies have shown that voting for your favorite open source project,
along with a healthy diet, reduces your potential for chronic lameness
and boredom. Vote Now at http://www.sourceforge.net/community/cca08
_______________________________________________
Plone-docs mailing list
Plone-docs@...
https://lists.sourceforge.net/lists/listinfo/plone-docs

Wichert Akkerman

Re: Sphinx for Plone doc ?

Reply Threaded

Previously Dylan Jay wrote:

> Wichert Akkerman wrote:
> > Previously Dylan Jay wrote:
> >> Martin Aspeli wrote:
> >>> Hi Dylan,
> >>>
> >>>> I think a key difference is that IMO PHC promotes lots of versions of
> >>>> documentation. Each tutorial is an island created by one person at one
> >>>> time.
> >>> True, but likely so is a file in svn. :)
> >>>
> >>>> I'm not sure how sphinx works but the end result looks more like a
> >>>> cohesive explanation of how stuff works and fits togeather. What is
> >>>> their update process?
> >>> Sphinx just generates HTML from reST files associated with packages.
> >>> That's why it works well for developer/low-level documentation. I write
> >>> readme's and doctests for my packages, and Sphinx makes them accessible
> >>> in a nice way.
> >>>
> >>>> Hopefully the missing piece for PHC is editors to make the individual
> >>>> submissions into a whole.
> >>> Right. The current documentation isn't suffering from a technology
> >>> problem, it's suffering (less than it used to, it must be said) from the
> >>> all too familiar problem that to a lot of people, writing documentation
> >>> is not as fun as writing code, and updating and editing documentation is
> >>> even more onerous.
> >>>
> >>> For example, I doubt we'd get Laura or JoAnna or Donna to write
> >>> documentation in reST in svn. Not because they couldn't, but because
> >>> that kind of environment isn't geared for that type of user or that type
> >>> of documentation. Even figuring out where to put it would be awkward.
> >>> reST is awkward. Lack of WYSIWYG is awkward.
> >>>
> >>> And by the same token, we won't necessarily get Kapil or Hanno or Sidnei
> >>> to write documentation for their packages in the PHC, although they do
> >>> often write excellent developer documentation that's embedded with the
> >>> code. Sphinx could let us make that more accessible to people. I don't
> >>> think it'll solve any other problems for us.
> >
> > Which immediately makes me conclude that Sphinx would be ideal to build
> > reference documentation (which do don't have at all right now) while PHC
> > is great for other types of documentation.
>
> I'd like to see a consistent set of PHC docs combined with api type
> reference docs from the code in such a way that they were released in
> conjunction with plone releases (of course there might have to be a lag)
>
> e.g. The plone 3.1 docs. The plone 3.0 docs. The plone 3.5 docs.
>
> That might mean for each release the editors of each PHC section
> selecting a subset of the tutorials etc that togeather make an
> up-to-date and *consistent* set of documentation to represent that
> release. Its all tagged and is then available at a url that indicates
> which release it belongs to.

That will never happen unless we magically increase the number of people
working on documentation by a factor of 10.

It may be interesting to read the grok-dev archive for the last month or
so. Grok is moving in exactly this direction: sphinx-based reference
documentation which is maintained in svn and has separate branches for
the separate grok releases combined with tutorials in PHC. Both are
shown on grok.zope.org.

Wichert.

--
Wichert Akkerman <wichert@...> It is simple to make things.
http://www.wiggy.net/ It is hard to make things simple.

-------------------------------------------------------------------------
Sponsored by: SourceForge.net Community Choice Awards: VOTE NOW!
Studies have shown that voting for your favorite open source project,
along with a healthy diet, reduces your potential for chronic lameness
and boredom. Vote Now at http://www.sourceforge.net/community/cca08
_______________________________________________
Plone-docs mailing list
Plone-docs@...
https://lists.sourceforge.net/lists/listinfo/plone-docs

vedaw

Re: Sphinx for Plone doc ?

Reply Threaded

I think we can at least work surfacing the docs based on version number
through views. I've put together a design for the plone.org/products section
that utilizes this concept, and the hope was that the view that breaks out
these versions could be re-used for the docs section as well.

This is a policy change that SteveM and I have been chatting about but we
hadn't gotten to a decision or to the implementation stage. I personally
like the idea, and it means that the currently supported versions (2.5 and
3.0, plus older docs) are split out but still available.

As for making tutorials, etc. not contradict each other, a lot of that will
ride on having people on the docs team garden properly. I think it would
also behoove us to beef up the manuals to be the core set of docs with
tutorials and how-tos being utilized for unusual use cases and "real world"
examples. When a new version of Plone comes out, we just copy the old manual
and revise as needed. That will reduce maintenance and focus the
documentation better.

I can't really speak to how the api docs would fit in here, but if you can
define better what it is you hope to see, perhaps someone will volunteer to
do the work.

- Veda

On 7/6/08 7:06 PM, "Dylan Jay" <gmane@...> wrote:

>
> I'd like to see a consistent set of PHC docs combined with api type
> reference docs from the code in such a way that they were released in
> conjunction with plone releases (of course there might have to be a lag)
>
> e.g. The plone 3.1 docs. The plone 3.0 docs. The plone 3.5 docs.
>
> That might mean for each release the editors of each PHC section
> selecting a subset of the tutorials etc that togeather make an
> up-to-date and *consistent* set of documentation to represent that
> release. Its all tagged and is then available at a url that indicates
> which release it belongs to.
>
> What I mean by consistent is tutorials/howtos etc that don't contradict
> each other or make confusingly different suggestions on the approach to
> solve problems.