[Zope-dev] [RfC] Removal of old stuff in Zope 2.10

[Paul Winkler]

On Tue, Dec 20, 2005 at 08:18:18PM +0000, Jens Vagelpohl wrote:
> I would say the only benefit was the unification of docs for Zope and  
> installed third party products in one place, 

Good point!

> and its "context- 
> sensitivity" for documenting screens in the ZMI when you're on them  
> by clicking the link. I've always tried to be good about it, and most  
> of my software has relatively up-to-date HelpSys documentation.

Me too.
 
> On the other hand I believe most product authors don't use HelpSys  
> documentation, and the Zope-provided pieces are way less current and  
> informative than the Zope book (2.7 version).

Yes. I think we as a community have a general documentation maintenance
problem.  It is something that neither ZC nor the community at large has
placed sufficient value on - understandably! Free docs don't pay
anybody's bills. There needs to be a driving force here stronger than
"it would be nice to have better docs", or there never will be. Maybe
once the Zope Foundation is up and running, I will propose that the
Foundation play a role. Maybe fundraising and earmarking funds for doc
work would help.  (... oh crap, I forgot about the foundation chat today.
Probably would have been OT at this stage anyway.)
 
> IMHO it would be nice if the HelpSys could be changed so that it  
> still provides those Help! links, but the product author can simply  
> assign a URL to them to point to a place where they copied and pasted  
> their docs into a website. That's not too much of an imposition on  
> product authors I think.

I think that would work.

If so, the question then becomes: timetable and plan for deprecating
HelpSys.  I don't think we can simply rip out registerHelp() in 2.10
unless we have deprecation warnings in 2.9; and a useful deprecation
warning requires something in place we can advise people to do instead.

-- 

Paul Winkler
http://www.slinkp.com