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