Re: Plone deployment manual

I seem to have stepped into a minefield. :)  

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 new things ("new" meaning "not Plone"), and, yes, I'm a techie but I still want to do as little extra work as possible.  Dylan, it's not that I or other technical contributors CAN'T learn restructured text, but 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.  

Ideally, contributors would have as low a barrier as possible, to avoid discouraging them from contributing.  When I contribute a "how to" to my own site (uwosh.edu/ploneprojects) I don't even want to have to THINK, so I have a link on the site that takes me to the how to folder'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 work long term are those that gain wide acceptance.  It would be self defeating for the Plone community to have competing documentation processes and venues.

How about this: I will take a portion of the Plone user manual and get it into cnx.org, then show y'all what I think are the cool things one can do with it there.

About hosting documentation (which, to quibble, doesn't have quite the same meaning to me as "deployment") I was also thinking about a repo for configuration files.  Is there such a thing already?  I think it should be outside the documentation, since documentation such as manuals/guides are linear.

	Kim

On Jul 28, 2011, at 9:59 AM, Alex Clark wrote:

> Hi,
> 
> On 7/28/11 10:15 AM, T. Kim Nguyen wrote:
>> Thanks Dylan.
>> 
>> I'm afraid that contributors (including me) will be scared off by the fairly complex learning and setup required to add to this documentation (Sphinx, collective commit rights, svn, restructured text) as opposed to editing a Plone page (or equivalent).
>> 
>> Is the http://collective-docs.readthedocs.org/en/latest/hosting/index.html documentation updated the same way?
> 
> 
> Yup, and this is exactly why we've been stalled on documentation for 
> years now. We have two competing camps who have very strong preferences 
> about how they contribute/edit documentation[1]. The c-docs are the only 
> "excitement" we've seen lately IMHO.
> 
> The good news though, is that GitHub actually supports TTW editing. So 
> in the case of the hosting docs Dylan just mentioned, one could edit 
> them TTW by going here:
> 
> 
> * 
> https://github.com/collective/collective.developermanual/blob/master/source/hosting/apache.txt
> 
> 
> Of course, you'd have to be familiar with restructured text, but that is 
> a fair compromise IMHO (I.e. you don't have to understand Sphinx or 
> collective commit rights at least.)
> 
> Anyway, if we want to encourage folks to contribute docs on plone.org by 
> using Plone, then we should be doing a much better job at managing 
> plone.org. Maybe the connexions thing could solve or address this 
> somehow (by lightening the plone.org/PHC load.) *shrug*
> 
> 
> 
> Alex
> 
> 
> 
> 
> [1] I feel pretty strongly that the FWT should grab some sane set of 
> documentation from the various offerings and ship it, versioned, with 
> each major release of Plone. But I've not gotten enough buy in to 
> consider an actual PLIP (where I'd happily do the work.)
> 
> 
> 
>> 
>> 	Kim
> 
> 
> 
>> 
>> On Jul 27, 2011, at 12:11 AM, Dylan Jay wrote:
>> 
>>> My opinion (and keep in mind it is just my opinion) is that the place for this and all future development manual work should be
>>> 
>>> http://plone.org/documentation/manual/plone-community-developer-documentation
>>> 
>>> which is edited via reST and sphinx and github as per these instructionshttp://plone.org/documentation/manual/plone-community-developer-documentation/introduction/writing
>>> 
>>> NOTE: at the time of writing this that document is out of date and the secondary copy at readthedocs is now more up to date.
>>> http://collective-docs.readthedocs.org/en/latest/introduction/writing.html. We're working on fixing this so the plone.org version would be updated nightly.
>>> 
>>> My suggestion is we deprecate all other developer manuals and KB articles which overlap with the collective developer manual and concentrate on cleaning up and making this manual both clean, easy to understand and comprehensive.
>>> 
>>> With regard to deployment I'd suggest we enhance the "hosting" section of this manual
>>> 
>>> http://collective-docs.readthedocs.org/en/latest/hosting/index.html
>>> 
>>> 
>>> Note: these comments don't apply to the users manual or other kinds of documentation.
>> 
>> 
>> ------------------------------------------------------------------------------
>> 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
> 
> 
> -- 
> Alex Clark · http://aclark.net
> 
> 
> ------------------------------------------------------------------------------
> 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
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/plone-docs


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