Re: Proposal to manage documentation similar to (or along with) core software.

Aloha,

Been following this thread silently...a comment from my docs-user 
testing perspective:
It would be really (really, really) nice to know more clearly and 
immediately and up-front which plone version(s) a doc is both relevant 
to and correct for. I think this is part of the aim with a "release" of 
docs, yes?

And, glad you are making clear that docs will not vanish from other 
access routes just because they are part of a release. I assumed not, 
and, good to see it in cyber-print.

thanks,
John S.


Alex Clark wrote:
> On 2010-04-19, Israel Saeta Pérez <[email protected]> wrote:
>> Hello there,
>> We just need a clean UI to make sure people understand that they can 
>> edit and create docs in the KB freely. Limi is working on this.
> 
> Don't get me wrong, I think the KB is great. And if PHC is a good tool to use to 
> create a KB, even better. What I am trying to get people to move towards though
> is a *release*.
> 
> Using the example you pointed me to the other day, you can look at 3 different
> versions of the Django FAQ:
> 
> http://docs.djangoproject.com/en/dev/faq/
> http://docs.djangoproject.com/en/1.0/faq/
> http://docs.djangoproject.com/en/1.1/faq/
> 
> And here is another example, versioned installation docs from Zenoss:
> 
> http://community.zenoss.org/community/documentation/official_documentation/installation-guide
> 
> We should be doing the same with Plone's documentation, IMHO.
> 
>> I think there's some confusion in my mind about this point. I'm not sure 
>> if with "doc release" you mean separate docs or just pointing to updated 
>> ones. 
> 
> I mean the documentation included in the release, which could come from
> any number of sources. Just because it makes into a release, does not
> mean it disappears from somewhere else e.g. the KB or Collective docs.
> 
>> In the first case, as said earlier, maintaining all the previous 
>> releases (to fix erratas or add info) can become cumbersome.
> 
> If you view making a release as cumbersome, you are right: it is. 
> Developing and releasing Plone is cumbersome too :-p.
> 
>> I think that, for now, we can just use the appropiate field to indicate 
>> that certain documents apply to Plone 4 and create a collection from 
>> them, or manually link them all (not so many) in a page if needed.
> 
> Right, that is the status quo. If we start *releasing* documentation
> for Plone though, I'd guess the soonest release we could do it with,
> and most likely target is 4.1.
> 
>> Only for new stuff, like existing PLIPs are for new features.
> 
> No, not only for new stuff (documentation), but for a particular 
> release (of existing documentation). A PLIP is an improvement
> proposal and take many forms e.g. adding, removing, restructuring.
> It would probably be pretty easy to mimick the FWT PLIP process,
> or join it.
> 
>> [...]
> 
>> If everybody believes that the figure of a "doc team leader" is 
>> necessary, meaning the one who manages the efforts and levels the field 
>> so everybody can contribute easily, but not the one who writes all the 
>> documentation (which should be written by the developers themselves), 
>> I'd be glad to serve.
> 
> Great! I think that makes you the doc team leader (technically
> release manager, in FWT-speak). Note: I have made this proposal to
> the Foundation board and members and I expect a response, but I'm not 
> going to pursue it. I hope they decide in favor and that you and/or 
> future "documentation release managers" decide to pursue it. 
> But either way, it's been a productive conversation IMHO.
> 
>> Cheers,
>> -- israel
>>
>>
>> ------------------------------------------------------------------------------
>> Download Intel&#174; Parallel Studio Eval
>> Try the new software tools for yourself. Speed compiling, find bugs
>> proactively, and fine-tune applications for parallel performance.
>> See why Intel Parallel Studio got high marks during beta.
>> http://p.sf.net/sfu/intel-sw-dev
>> _______________________________________________
>> Plone-docs mailing list
>> [email protected]
>> https://lists.sourceforge.net/lists/listinfo/plone-docs
> 
> 

-- 
John Schinnerer - M.A., Whole Systems Design
--------------------------------------------
- Eco-Living -
Whole Systems Design Services
People - Place - Learning - Integration
[email protected]
http://eco-living.net

------------------------------------------------------------------------------
_______________________________________________
Plone-docs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/plone-docs