Re: kb -> c.developermanual

On 8 Jul 2011, at 04:01, Alex Clark <[email protected]> wrote:

> Hi Jon,
> 
> On 7/7/11 10:19 PM, Jon Stahl wrote:
>> On Thu, Jul 7, 2011 at 6:02 PM, Dylan Jay<[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,
> 
> 
> That has been accomplished via funnelweb, it's just not automated/kept 
> up to date yet:
> 
> * 
> http://plone.org/documentation/manual/plone-community-developer-documentation
> 
> 
> and have that be the One True Single
>> Source for all this great documentation work.
> 
> 
> Inasmuch as the goal is to synchronize the Sphinx documentation daily 
> with PHC content, plone.org/documentation is the One True Single Source.
> 
> Personally, I don't like reading docs in PHC on plone.org so I created 
> collective-docs.plone.org to host the "pure" Sphinx docs. I agree this 
> creates confusion, but I believe that it can be mitigated via some 
> "portal message" style notification about the multi-homed nature of the 
> c-docs in any Sphinx hosted instance (as well as some notice about 
> "imported via funnelweb" inside 
> plone.org/documentation/manual/plone-community-developer-documentation)
> 

This sounds to me a singularly bad idea. Having the same things in two places and not putting our documentation on our primary (Plone!) website sends confused, not very reassuring messages. No amount of warning message will mitigate that.

If you personally don't like using plone(.org), I think you should run a local build of the Sphinx docs, not use plone.org for this purpose.


> Since you chimed in, can I interest you in trying to push this along?
> 
> * http://dev.plone.org/plone/ticket/11771
> 
> Would like the board to formally OK my next steps, and I've not heard 
> back from Cal.
> 
> 
> 
> 
> Alex
> 
> 
> 
> 
> 
> 
> 
>> 
>> :jon
>> 
>> ------------------------------------------------------------------------------
>> 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
> _______________________________________________
> Plone-docs mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/plone-docs

------------------------------------------------------------------------------
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
_______________________________________________
Plone-docs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/plone-docs