> -----Original Message-----
> From: Ricardo Alves [mailto:
[hidden email]]
> Sent: Sunday, 23 November 2008 4:37 AM
> To:
[hidden email]
> Subject: Re: [Plone-docs] If core code is undocumented it's broken
> (Was:where should developer documentation go?)
> > Personally you can count my contributions out from anything but Wiki. I
> am
> > tired with the state of documentation and how hard it to get anything
> fixed
> > there.
>
> I hope you reconsider, Mikko, since you've done lots of useful
> contributions. I agree it is difficult to get anything fixed on other
> docs. That's something that will probably be improved in the new
> plone.org, I hope...
I've can go fix things in other peoples docs then that's open editing.
That's a wiki. So we're not really arguing are we?
IMO keeping the developer documentation cohesive so it makes sense as a
whole is the most important thing we can do to help. I'm hoping everyone
agrees with me till this point.
I think the current document process inherently creates contradictory
documentation by virtue of the fact that the common recourse for correcting
incorrect documentation is to create a new competing document.
To be honest its not really the reviewing that's the problem with the PHC
it's the fact that every gets to own their own opinion, all on different
pages. PHC is like documenting software by getting a 100 people to write
separate blogs on it. Asking editors to mediate that is like cat hearding.
Why not one document we all work on?
To improve this situation we could have official documents with tightly
controlled subject areas aka books alongside openediting/wiki documents to
cover the rapid innovations not covered in official docs. The subset of
people who can edit the official manuals could be smaller but it should be
one voice, anyone in that group can edit any page without permission so we
have one cohesive voice.
I have heard peoples reservations about these ideas and others. Here they
are but if I've missed any feel free to add them to the list.
Wikis (
- It's too much of a risk to turn all the docs into wikis
- I agree. I think we should split our documentation between "official"
and "community"
- They were tried and failed on Plone.org
- djj: wikipedia. Besides, can't be worse than we have now.
- They are unstructured
- djj: wikipedia. Besides you don't need the wikilinking, you can just
make it open editing and you can even set it to review page title changes
while leaving body content opening for editing by any member. That's still a
wiki.
- They won't provide enough review
- djj: you can review them after editing via email notifications.
- I want to see who the author is
- djj: seeing the author hasn't stopped incorrect/confusing documentation
appearing so far.
- wikis are anti-document management
- djj: I'm not entirely sure what that means but I would think document
management is any process that produces quality documentation as a result.
Sphinx
- It's not eating our own dog food
- djj: true and that could be embarrassing but also consider that Plone is
a web content management system that does a decent job of document
management but it's certainly not designed as a tool for compiling large
documents for various sources. It's not a doc generator. I'd argue that
keeping documentation together such that it makes sense as a whole is the
most important thing. Apis should go into developer docs.
- It's not as easy to edit
- djj: also true but it is easy for developers to edit and no one
suggested using sphinx for anything other developer docs.
- It only does api docs
- djj: it's a document generator framework. It makes books from rst files.
Any kind of books.
- it only should be used for api docs
- djj: I'd argue that keeping documentation together such that it makes
sense as a whole is the most important thing.
- it's too radical a change
- djj: it's proven, it works and it its less effort than some other
suggestions to update PHC for developer 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
