Re: Plone deployment manual

On 29/07/2011, at 9:32 AM, T. Kim Nguyen wrote:

> 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. :)

yes I understand your reaction. I'd say however that encouraging  
people to contribute is not our biggest problem. Already anyone can  
submit a KB article using plone. And many have done so. So already  
this problem is solved.

Our biggest problem IMO is of consolidation, ie letting someone  
contribute documentation to the right place so there aren't multiple  
different out of date versions of the same advice in different places.  
So we want people to THINK because not thinking of how they can  
combine or improve others efforts has got us to the current state of  
documentation we are in today.

Admittedly the c.docs is heading in the same way of having multiple  
places talking about the same topics but we'll clean that up soon  
enough :)

The goal is one developer manual which you can read end to end and it  
makes sense and doesn't contradict itself or repeat itself. And yet is  
still reasonably easy to contribute to.

The other aspect is we want core developers to document their own  
apis. Core developers are already using git/svn. Sphinx makes is  
incredibly easy to include docs from code into our manual. I've  
already done this for several of the GS module level docs (which I had  
to add). The easier we make this for them the better. The system is  
broken if we expect non-developers to document developers code because  
they won't.



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

sure, can't do any hard with regard to the users manual but you might  
want to talk to the people who maintain the users manual. I've lost  
track of who that is.

>
> About hosting documentation (which, to quibble, doesn't have quite  
> the same meaning to me as "deployment") I was also

I was suggesting renaming hosting to deployment.

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

yes there is zopeskel. Also those at the sauna sprint are working on  
improving these aspects of zopeskel now I believe.

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