I seem to have stepped into a minefield. :) =20
I come in peace! I was just sharing my reaction to how I would have =
to install a bunch of software on a computer, and learn a bunch of ne=
w things ("new" meaning "not Plone"), and, yes, I'm a techie but I st=
ill want to do as little extra work as possible. Dylan, it's not tha=
t I or other technical contributors CAN'T learn restructured text, bu=
t that we'd have to use git or svn or Sphinx, and those tools are not=
as easy to use as Plone or cnx.org. =20
Ideally, contributors would have as low a barrier as possible, to avo=
id discouraging them from contributing. When I contribute a "how to"=
to my own site (uwosh.edu/ploneprojects) I don't even want to have t=
o THINK, so I have a link on the site that takes me to the how to fol=
der's createObject call. That's what I mean by making it super super=
easy... frictionless, superconducting, K-Y for process. :)
Alex, yes I could just forge ahead but I know the only efforts that w=
ork long term are those that gain wide acceptance. It would be self =
defeating for the Plone community to have competing documentation pro=
cesses and venues.
How about this: I will take a portion of the Plone user manual and ge=
t it into cnx.org, then show y'all what I think are the cool things o=
ne can do with it there.
About hosting documentation (which, to quibble, doesn't have quite th=
e same meaning to me as "deployment") I was also thinking about a rep=
o for configuration files. Is there such a thing already? I think i=
t should be outside the documentation, since documentation such as ma=
nuals/guides are linear.
=09Kim
Hi,
=20
Post by T. Kim NguyenThanks Dylan.
=20
I'm afraid that contributors (including me) will be scared off by =
the fairly complex learning and setup required to add to this documen=
tation (Sphinx, collective commit rights, svn, restructured text) as =
opposed to editing a Plone page (or equivalent).
Post by T. Kim Nguyen=20
Is the http://collective-docs.readthedocs.org/en/latest/hosting/in=
dex.html documentation updated the same way?
=20
=20
Yup, and this is exactly why we've been stalled on documentation fo=
r=20
years now. We have two competing camps who have very strong prefere=
nces=20
about how they contribute/edit documentation[1]. The c-docs are the=
only=20
"excitement" we've seen lately IMHO.
=20
The good news though, is that GitHub actually supports TTW editing.=
So=20
in the case of the hosting docs Dylan just mentioned, one could edi=
t=20
=20
=20
*=20
https://github.com/collective/collective.developermanual/blob/maste=
r/source/hosting/apache.txt
=20
=20
Of course, you'd have to be familiar with restructured text, but th=
at is=20
a fair compromise IMHO (I.e. you don't have to understand Sphinx or=
=20
collective commit rights at least.)
=20
Anyway, if we want to encourage folks to contribute docs on plone.o=
rg by=20
using Plone, then we should be doing a much better job at managing=
=20
plone.org. Maybe the connexions thing could solve or address this=
=20
somehow (by lightening the plone.org/PHC load.) *shrug*
=20
=20
=20
Alex
=20
=20
=20
=20
[1] I feel pretty strongly that the FWT should grab some sane set o=
f=20
documentation from the various offerings and ship it, versioned, wi=
th=20
each major release of Plone. But I've not gotten enough buy in to=
=20
consider an actual PLIP (where I'd happily do the work.)
=20
=20
=20
=20
=20
=20
Post by T. Kim Nguyen=20
=20
My opinion (and keep in mind it is just my opinion) is that the p=
lace for this and all future development manual work should be
Post by T. Kim Nguyen=20
http://plone.org/documentation/manual/plone-community-developer-d=
ocumentation
Post by T. Kim Nguyen=20
which is edited via reST and sphinx and github as per these instr=
uctionshttp://plone.org/documentation/manual/plone-community-develope=
r-documentation/introduction/writing
Post by T. Kim Nguyen=20
NOTE: at the time of writing this that document is out of date an=
d the secondary copy at readthedocs is now more up to date.
Post by T. Kim Nguyenhttp://collective-docs.readthedocs.org/en/latest/introduction/wri=
ting.html. We're working on fixing this so the plone.org version woul=
d be updated nightly.
Post by T. Kim Nguyen=20
My suggestion is we deprecate all other developer manuals and KB =
articles which overlap with the collective developer manual and conce=
ntrate on cleaning up and making this manual both clean, easy to unde=
rstand and comprehensive.
Post by T. Kim Nguyen=20
With regard to deployment I'd suggest we enhance the "hosting" se=
ction of this manual
Post by T. Kim Nguyen=20
http://collective-docs.readthedocs.org/en/latest/hosting/index.ht=
ml
Post by T. Kim Nguyen=20
=20
Note: these comments don't apply to the users manual or other kin=
ds of documentation.
Post by T. Kim Nguyen=20
=20
------------------------------------------------------------------=
------------
Post by T. Kim NguyenGot Input? Slashdot Needs You.
Take our quick survey online. Come on, we don't ask for help ofte=
n.
Post by T. Kim NguyenPlus, you'll get a chance to win $100 to spend on ThinkGeek.
http://p.sf.net/sfu/slashdot-survey
=20
=20
--=20
Alex Clark =B7 http://aclark.net
=20
=20
-------------------------------------------------------------------=
-----------
Got Input? Slashdot Needs You.
Take our quick survey online. Come on, we don't ask for help often=
.
Plus, you'll get a chance to win $100 to spend on ThinkGeek.
http://p.sf.net/sfu/slashdot-survey
_______________________________________________
Plone-docs mailing list
https://lists.sourceforge.net/lists/listinfo/plone-docs