Hi folks,
I've been doing some work on the Wine Developer's Guide. It's in better shape now, but I'd still rate it at 2.5 stars. It still needs some work until it's production quality, but the end is in sight. In fact, if Lionel can look at the OpenGL section (lots of things changed in there lately), and Eric at the Multimedia section (lots of things out of date), we'd be so much closer.
Instead of sending all the updates as one big patch, I've tried to split them up, for all the known reasons. But before I start sending patches, I have a few comments about this documentation business.
First, we have to resist the temptation to add a lot of redundant information. Like what is cvs, how it functions, etc. There are better resources available on the web, and we simply don't have the manpower to maintain, translate, etc. all this information. Having a lot of documentation may give us a warm and fuzzy feeling, but in fact it just shows how we have failed to make Wine transparent, and/or we haven't refined the docs. Nobody likes to read documentation, so let's keep it short, sweet, and interesting.
Second, we have to avoid at all cost including information that can change often. We get an update for these docs only once every few years, and having obsolete information in there is way worse than having no information at all. There are better places to put such info: man pages, web pages (WineHQ), etc. Having it duplicated somewhere in the depths of these manuals serves no purpose then to create more (and useless) work for us.
Third, we have to try to make these things look as books, and less likely a motley collection of files, interlaced with TODOs/FIXMEs/etc.
-
Dimitrie O. Paun