Re: kb -> c.developermanual

On 7/8/11 12:58 AM, Dylan Jay wrote:
>
> On 08/07/2011, at 2:50 PM, Alex Clark wrote:
>
>> On 7/7/11 11:05 PM, Alex Clark wrote:
>>> On 7/7/11 10:56 PM, Dylan Jay wrote:
>>>> On 08/07/2011, at 12:19 PM, Jon Stahl wrote:
>>>>
>>>>> On Thu, Jul 7, 2011 at 6:02 PM, Dylan Jay<dylan-Q+/Sk2sTzaxWk0Htik3J/[email protected]>
>>>>> wrote:
>>>>>>
>>>>>> On 07/07/2011, at 11:39 AM, Alex Clark wrote:
>>>>>>
>>>>>>> Hi.
>>>>>>>
>>>>>>> On 6/19/11 7:36 AM, Dylan Jay wrote:
>>>>>>>> Hi,
>>>>>>>>
>>>>>>>> There's lots of links in the collective developers manual to KB
>>>>>>>> articles. Is there any reason not to just import those documents
>>>>>>>> directly into the manual and remove the KB article?
>>>>>>>
>>>>>>> Yes.
>>>>>>>
>>>>>>> I'll state the obvious: because it may offend the KB article
>>>>>>> author. I
>>>>>>> suspect you'd need to contact the author directly and ask where
>>>>>>> they'd
>>>>>>> prefer their article to live.
>>>>>>
>>>>>> seems a shame as where we really want to go is non-repeated
>>>>>> documentation.
>>>>>> but I guess you're right, not worth coming up with a process
>>>>>> until we
>>>>>> get manual publishing working.
>>>>>>
>>>>>>
>>>>>>>
>>>>>>> Note: we've still got a "mess" on our hands wrt to collective
>>>>>>> docs.
>>>>>>> I am
>>>>>>> hoping to clean up and automate the inclusion of c-docs in
>>>>>>> plone.org
>>>>>>> as
>>>>>>> soon as someone from the board replies to this ticket:
>>>>>>>
>>>>>>> * https://dev.plone.org/plone/ticket/11771
>>>>>>>
>>>>>>>
>>>>>>> Right now we have:
>>>>>>>
>>>>>>> * Out of date c-docs on plone.org/documentation (because no one
>>>>>>> understands the upload process[1]). I'm now OK with fixing this
>>>>>>> (i.e. I
>>>>>>> know how to do it).
>>>>>>
>>>>>> I'm happy to fix any coding issues with the funnelweb import. Last
>>>>>> time I tried it was working.
>>>>>>
>>>>>>
>>>>>>>
>>>>>>> * Out of date c-docs on collective-docs.plone.org because your
>>>>>>> recent
>>>>>>> changes added a Sphinx module that does not exist on deus
>>>>>>> (includedocs
>>>>>>> IIRC).
>>>>>>
>>>>>> :) sorry about that. But will be worth it if all goes to plan
>>>>>> and we
>>>>>> can kick start core devs into documenting their own work.
>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> As I am not terribly interested in fixing deus[2], I've recently
>>>>>>> considered moving c-docs to github and publishing them to
>>>>>>> readthedocs.org (which moo has +1'd). But I still need to test.
>>>>>>
>>>>>> So replace collective-docs.plone.org with readthedocs? I think
>>>>>> that's
>>>>>> a good idea.
>>>>>
>>>>> I'm not totally sure I'm up to speed with everything, but just
>>>>> wanted
>>>>> to restate that I hope the goal is still to integrate collective-
>>>>> docs
>>>>> into Plone.org/documentation, and have that be the One True Single
>>>>> Source for all this great documentation work.
>>>>
>>>> yes absolutely.
>>>>
>>>> and in addition to plone.org/documentation I think what's being
>>>> proposed is
>>>> - collective-docs.plone.org to be decomissioned.
>>>
>>>
>>> Well, it's currently broken, in that it can't be updated without
>>> installing some Sphinx module in Python (I think). But other than
>>> that I
>>> still like idea of a "sphinx home" for the c-docs.
>>>
>>>> - a new mirror of the collective-docs to go somewhere like http://readthedocs.org/docs/plone-developers-manual
>>>
>>> Yeah, if the readthedocs.org test works out, then c-docs.plone.org
>>> could
>>> be redirected there. Or it could be redirected to p.org/
>>> documentation. I
>>> don't have any strong preference wrt to that.
>>
>> It worked!!! We now have (almost) instantaneous updates to the c-docs
>> documentation (as published on readthedocs.org) via github service
>> hooks.
>>
>> * c-docs moved to github:
>> http://dev.plone.org/collective/changeset/242079/collective.developermanual
>>
>> * Github repo: https://github.com/collective/
>> collective.developermanual
>>
>> * Readthedocs: http://collective-docs.readthedocs.org
>>
>> * Old c-docs updated: http://collective-docs.plone.org
>
> btw, can we call it the plonedevdocs or plonedevelopersmanual or
> somesuch on readthedocs? Collective-docs doesn't make much sense to
> the outside world.

Maybe :-). I'm not opposed to changing the name. But I'm not convinced 
there is a better alternative.

We currently have several public facing names for the c-docs:

1. Plone Community Managed Developer Manual
2. Plone Developer Manual (from the sphinx source/introduction title, 
which I've just fixed to be the same as #1)
3. Collective docs
4. Plone Community Developer Documentation (from 
http://plone.org/documentation/manual/plone-community-developer-documentation)


But really, c-docs work IMHO opinion, both because there is some 
"Collective" brand recognition in the Python world now, and the docs do 
in fact live in the collective.


Maybe Jon Stahl or Martin or somebody will give us some tips. Since we 
know we want these docs to ultimately live inside 
plone.org/documentation (as Plone Community Developer Documentation ) 
then perhaps the collective URL should be:

plone-community-developer-documentation.readthedocs.org


But that's a mouthful. Still, I'd consider it (I don't particularly 
like: plonedevdocs or plonedevelopersmanual).



Alex









>
>
>
>
> ------------------------------------------------------------------------------
> All of the data generated in your IT infrastructure is seriously valuable.
> Why? It contains a definitive record of application performance, security
> threats, fraudulent activity, and more. Splunk takes this data and makes
> sense of it. IT sense. And common sense.
> http://p.sf.net/sfu/splunk-d2d-c2


-- 
Alex Clark · http://aclark.net


------------------------------------------------------------------------------
All of the data generated in your IT infrastructure is seriously valuable.
Why? It contains a definitive record of application performance, security 
threats, fraudulent activity, and more. Splunk takes this data and makes 
sense of it. IT sense. And common sense.
http://p.sf.net/sfu/splunk-d2d-c2