On Wed, 2008-12-03 at 14:34 +0100, Nelson Benítez León wrote: > I think nowadays, thanks to library.gnome.org, most people use online > documentation, it's way more practical because you don't have to > install any package, it's always up-to-date, it has a good google > search and you can open the information in several tabs with your > browser. > > But I don't think this is an online vs offline documentation question, > I'm talking about adding a feature to the online docs, if people want > later to add that feature to the offline docs they can, just save the > html output of the online docs to disk in some browseable format. I strongly disagree with this, and while I can't speak for everyone, I'll join Ross in saying that I always use Devhelp over library.gnome.org. You can use tabs in Devhelp, and its search has never failed me. One of the main advantages of Devhelp, as Ross says, is that the documentation you have installed is tied to the library versions against which you're developing, so you don't get into muddles over changed/added/removed API. > I don't like this approach, it requires manpower, and what is worse, > someone who decides what is useful and whatnot, that is subjective, I > prefer there's an official documentation with no comments, and the > online documentation with the possibility to add comments. Just like > in www.php.net/docs.php where you have the online documentation with > comments, and if you choose to download the documentation (eg. to > consult it offline) then you get the official version with no > comments. Developers moderating submitted improvements to the documentation is no more subjective than them moderating patches. They know the code and its behaviour the best, and it's only really a matter of making sure that they set a consistent baseline for how simple the documentation is (in terms of what it assumes the reader knows already). I don't see that as being a problem. I've used the online PHP documentation, and the comments on it are more often than not quite helpful, and very suitable for inclusion into the offline documentation. However, there are also many cases where the comments are incorrect or contradictory, and that's why periodic moderation (and merging into the source code) is required. Philip
Attachment:
signature.asc
Description: This is a digitally signed message part