Plone › Documentation Team

Plone.org documentation process considered harmful

26 messages

1 2

Kamon Ayeva-3 () Re: Plone.org documentation process considered harmful

Reply Threaded

In reply to this post by Rok Garbas

Hi Rok,

I have seen the result of your Sphinx work from the post you sent on
the plone-devel list.
This is great.
And hopefully, the process of incorporating new docs/updating will be
easier, since you don't have to go through a web interface, kupu
editor, and al. You just handle "text" with some formatting guidelines
to follow, right ?

I have a question about this http://docs.garbas.si/plone-latest/
Do you use a script to automatically update the source from what is
currently on plone.org ? I have been making small updates to the
Archetypes Developer Manual these days, with suggestions from Israel,
and also incorporating value-added comments that were added by people.
So the manual will be improved in the coming days.

Cheers,
kamon

-------------------------------------------------------------------------
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: Plone.org documentation process considered harmful

Reply Threaded

> -----Original Message-----
> From: Kamon Ayeva [mailto:[hidden email]]
> Sent: Thursday, 13 November 2008 12:22 AM
> To: [hidden email]
> Subject: Re: [Plone-docs] Plone.org documentation process considered
> harmful
>
> Hi Rok,
>
> I have seen the result of your Sphinx work from the post you sent on
> the plone-devel list.
> This is great.
> And hopefully, the process of incorporating new docs/updating will be
> easier, since you don't have to go through a web interface, kupu
> editor, and al. You just handle "text" with some formatting guidelines
> to follow, right ?
>
> I have a question about this http://docs.garbas.si/plone-latest/
> Do you use a script to automatically update the source from what is
> currently on plone.org ? I have been making small updates to the
> Archetypes Developer Manual these days, with suggestions from Israel,
> and also incorporating value-added comments that were added by people.
> So the manual will be improved in the coming days.

Hi Kamon,

It's not auto synched. It could be but I think a smarter way to go is to
decide where such manuals will "live" long term and then only have one
version. If these sphinx based docs had the look and feel of Plone.org and
were in the Plone.org domain would it work for you to update it via rst and
svn rather than kupu?

-------------------------------------------------------------------------
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: Plone.org documentation process considered harmful

Reply Threaded

In reply to this post by Ricardo Newbery-2

Hi Ric,

We're in the zone of subjective opinion. Talking won't prove what works
better so we'll just have to see.

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

> -----Original Message-----
> From: Ricardo Newbery [mailto:[hidden email]]
> Sent: Wednesday, 12 November 2008 9:44 PM
> To: [hidden email]
> Subject: Re: [Plone-docs] Plone.org documentation process considered
> harmful
>
>
> On Nov 12, 2008, at 12:36 AM, Dylan Jay wrote:
>
> >> As for using sphinx to document our API...well it's still only as
> >> good
> >> as what developers put in the API. If people aren't documenting their
> >> code then it won't be in there. Sphinx makes it look a lot nicer than
> >> the old api.plone.org, that's for sure. But until people change their
> >> habits and make documentation a priority, it's not going to help too
> >> much.
> >
> > Just to be 100% crystal clear: sphinx based docs can include non-api
> > documentation. It is a documentation tool which has the ability to
> > bring in
> > outside auto generated documentation. It is not an dressed up api doc
> > generator.
> >
> > The Plone sphinx based docs can and probably will become more like
> > the bfg
> > narrative docs
> >
> > http://static.repoze.org/bfgdocs/#narrative-documentation
> >
> > than the existing api.plone.docs.
>
>
> The repoze docs are very nice. Of course they have a smaller (i.e.
> "less ambitious and less featureful") codebase to document. A more
> ambitious example of sphinx based docs would be
> http://docs.python.org/dev/
>
> I'm intrigued but I'm not clear what sphinx buys you other than
> perhaps an easy way to incorporate API docs into a freeform narrative
> document,
>
>
>
> > Developers using Plone *need* narrative documentation.
> > Plone.org doesn't do that at least in its current unstructured form.
> > Sphinx
> > can and will and in the end it's a better place for it since the
> > collective
> > is more open, more transparent and more developer friendly than
> > Plone.org
> > docs, IMO.
>
>
> More open, transparent, developer-friendly? Perhaps. Sounds good,
> but what precisely do you mean by these terms?
>
> More open in the sense that anyone can contribute without editorial
> control? I'm not sure I care for that. Who will manage this? Even
> in the collective, someone assumes the responsibility to manage
> releases which can often mean reviewing, revising, and discarding
> contributions. Other than the lack of a built-in workflow, how would
> this svn-mediated editorial process be any different than editorial
> oversight on Plone.org?
>
> More transparent in that all contributions are publicly logged and
> tracked? I guess if we really feel this is necessary, it should be
> easy enough to make the edit history of Plone.org docs publicly
> accessible. But why?
>
> More developer-friendly due to reStructuredText and subversion? Are
> developers more comfortable with editing reStructuredText source docs
> in subversion repositories than using Kupu to edit documents in a
> Plone CMS? Shrug.
>
> More developer-friendly because the docs are edited alongside the
> developer's product code? Okay. But then, some of the best
> documentation comes from users and integrators, not from developers.
> How would non-developers get to contribute?
>
> Again, I'm intrigued. Definitely sounds like it could be an
> improvement over the plain vanilla api.plone.org. Might also be real
> nice if sphinx based docs could be incorporated into the add-on
> product documentation available at http://plone.org/products/. This
> certainly seems like it has the potential to encourage developers to
> document as they develop, but it isn't clear how any of this is
> *better* than the current relatively "open" and "user-friendly"
> process to contribute non-api documentation on Plone.org. Different,
> yes. Potentially useful, yes. Better? Seems a little like asserting
> that *book* documentation is better than *online* documentation. They
> can both be good but they tend to fill different niches. Which is
> better? Shrug.
>
> Ric
>
>
>
> -------------------------------------------------------------------------
> 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

Kamon Ayeva-3 () Re: Plone.org documentation process considered harmful

Reply Threaded

In reply to this post by Dylan Jay-4

On Wed, Nov 12, 2008 at 2:40 PM, Dylan Jay <[hidden email]> wrote:

>> -----Original Message-----
>> From: Kamon Ayeva [mailto:[hidden email]]
>> Sent: Thursday, 13 November 2008 12:22 AM
>> To: [hidden email]
>> Subject: Re: [Plone-docs] Plone.org documentation process considered
>> harmful
>>
>> Hi Rok,
>>
>> I have seen the result of your Sphinx work from the post you sent on
>> the plone-devel list.
>> This is great.
>> And hopefully, the process of incorporating new docs/updating will be
>> easier, since you don't have to go through a web interface, kupu
>> editor, and al. You just handle "text" with some formatting guidelines
>> to follow, right ?
>>
>> I have a question about this http://docs.garbas.si/plone-latest/
>> Do you use a script to automatically update the source from what is
>> currently on plone.org ? I have been making small updates to the
>> Archetypes Developer Manual these days, with suggestions from Israel,
>> and also incorporating value-added comments that were added by people.
>> So the manual will be improved in the coming days.
>
> Hi Kamon,
>
> It's not auto synched. It could be but I think a smarter way to go is to
> decide where such manuals will "live" long term and then only have one
> version. If these sphinx based docs had the look and feel of Plone.org and
> were in the Plone.org domain would it work for you to update it via rst and
> svn rather than kupu?

Yeah, my intuition tells me it would work "long term" for developer manuals.
And, yes, if I take my case, I would be eaiser/quicker working with
reST and svn.

-- Kamon

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

treed-2 () Re: Plone.org documentation process considered harmful

Reply Threaded

In reply to this post by Dylan Jay-4

On Wed, Nov 12, 2008 at 02:14:21PM +1100, Dylan Jay spake thusly:
> Wikis aren't anti-document management Joanna. They don't have to be
> unstructured.

I really like ZWiki. I really like that I can parent any page to any
other page and a table of contents is automatically generated on the
front page. My company documentat eventually filled out into something
organized somewhat like a book. It's pretty cool.

I joined this mailing list ages ago when it was first created but
haven't posted. Now I'm beginning another plone project so the current
status of documentation is once again of interest to me. :)

I just pre-ordered Practical Plone 3. I've been trying to make it
through Professional Plone Development (after having tried to get
through Practical Guide to Plone) and find them both quite difficult
to follow. The documentation seems to go from super newbie to really
advanced. Hopefully this new book will bridge the gap and once I get
the basic concepts of how to manipulate everything through the web I
will finally be able to follow Professional Plone Development and be
able to make filesystem based eggs/products.

--
Tracy Reed
http://tracyreed.org

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

attachment0 (196 bytes) Download Attachment

vedaw () Re: Plone.org documentation process considered harmful

Reply Threaded

The new book, Practical Plone, should indeed be easier. The idea was to gear
it towards newbies in general. Having read most of the chapters myself in
order to get them to the publisher, I think you'll find it helpful.

As far as Zwiki, my understanding is that plone.org/documentation previously
used Zwiki, and it was a bit of a disaster. That predates my experience with
Plone, however.

On 11/25/08 12:17 PM, "Tracy Reed" <[hidden email]> wrote:

> On Wed, Nov 12, 2008 at 02:14:21PM +1100, Dylan Jay spake thusly:
>> Wikis aren't anti-document management Joanna. They don't have to be
>> unstructured.
>
> I really like ZWiki. I really like that I can parent any page to any
> other page and a table of contents is automatically generated on the
> front page. My company documentat eventually filled out into something
> organized somewhat like a book. It's pretty cool.
>
> I joined this mailing list ages ago when it was first created but
> haven't posted. Now I'm beginning another plone project so the current
> status of documentation is once again of interest to me. :)
>
> I just pre-ordered Practical Plone 3. I've been trying to make it
> through Professional Plone Development (after having tried to get
> through Practical Guide to Plone) and find them both quite difficult
> to follow. The documentation seems to go from super newbie to really
> advanced. Hopefully this new book will bridge the gap and once I get
> the basic concepts of how to manipulate everything through the web I
> will finally be able to follow Professional Plone Development and be
> able to make filesystem based eggs/products.

1 2