Re: Plone deployment manual

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