Community
Participate
Working Groups
http://www.eclipse.org/documentation/main.html provides links to documentation for released versions of Eclipse. For example, it points to http://help.eclipse.org/help30/ which is the online help for the Eclipse 3.0.2 Platform. Presumably soon it will have /help31 which would be for Eclipse 3.1.0 Platform. There are two main problems with this I'd like to see addressed. 1. There is no link for the latest version of the help. What I mean is the help for the HEAD version or even the stable/milestone version. Why is this a problem? Consider bug 90358, bug 88043, and bug 85029. The developers pushed new documentation but there is no convenient way for the community to view it until it makes it into a build (like 3.1RC3) and we install the build and look at it then. It would be much better for us to be able to view that new page, in context, immediately as soon as it was pushed. Among other things this would reduce the time between when the author writes it and when the reader sees it and reports a problem in the doc, which is always a good thing. 2. This documentation only covers the Platform. It doesn't cover Web Tools, VE, or any of the other Eclipse projects. Why is this a problem? It's a problem for the developers and PMCs because they can't (without installing a bunch of stuff) see how their doc fits in with the rest of the doc in all of Eclipse. Does it fit the style? Does it duplicate info given elsewhere? Does all the doc look like it came from the same source? What best practices have other projects devised for their doc that I can use in mine? Also it's a problem for the community because of the lack of a stable URL. This comes up a lot: if someone asks a question on the newsgroup, I can't say 'open Window > Help contents > path > to > doc' because that may vary depending on what Eclipse version they have and it's easy for a new user to get confused trying to navigate that. Also I can't say 'click on this url, http://help.eclipse.org/helpXX/whatever' because it won't be there if the feature is not in a release version, and even if it did exist, any URL I give will be out of date if someone finds my message in the search archive because Eclipse versions keep marching onwards. Here's the proposed solution to solve these problems: I propose you create and maintain an infocenter (a live version of help for the stand-alone web server) that has all the latest doc for *all Eclipse projects*. It should take the xml, html, and image files directly from the CVS server when they are requested under the covers. It should have the regular look-n-feel, navigation, searching, and indexing - basically it should be exactly what I would get if I installed the HEAD version of every single eclipse.org project and subproject, combining all their help books and pages together, but without the hassle of downloading and installing and matching versions that would entail. Building help indexes nightly would be fine if they can't be updated continuously. I suggest using a base URL without a version number such as http://help.eclipse.org/help/, so for example you'd have stable URLs like http://help.eclipse.org/help/topic/org.eclipse.platform.doc.isv/guide/int_who.htm or http://help.eclipse.org/help/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/int_who.htm .
I do not see this as being a task for the Foundation. It is the responsibility of the project(s) to define their documentation strategy, not the Foundation. I could imagine the Foundation providing additional infrastructure, but it would have to be on the request of the PMCs. Another alternative would be to create a separate documentation project at Eclipse and use that team and community to drive the types of features you are requesting here.
Closing as WONTFIX, as per Mike's comments.
I somewhat disagree with Mike: I think that a centralized help system for Eclipse projects is an eclipse.org item, but I do agree with him that the Foundation cannot build this. Fortunately, Denis points out: "Actually, we *do* have a centralized URL: http://help.eclipse.org/ This URL is running three instances of an application called Eclipse: 3.1, 3.0 and 2.1, at http://help.eclipse.org/help31, http://help.eclipse.org/help30 and http://help.eclipse.org/help21 respectively. Any project who wants to host content there is more than welcome to send me their Infocenter help plugin(s) and tell me how to install it." We shouldn't be hitting the CVS repository for updates - that's just going to be too slow given the number of pages www.eclipse.org serves. We just need to add "send the help plug-in to webmaster@" as part of each project's release checklist.
+1 for adding doc plugins to the existing Infocenter help, as long as it doesn't mean too much work for me :) D.
+1. Centralized online help for all of the Eclipse projects would be a very useful resource for the community.
I installed Birt's help in the 3.1 Infocenter. Browse to http://help.eclipse.org/help31 and you should see it in the index. A few caveats: - I had to download and extract the birt report framework zip file, and correctly guess that the only directory I needed was in the org.eclipse.birt.doc dorectory - I don't need the whole project in the Infocenter, just the docs - Eclipse needed to be restarted on all nodes in the cluster to see the new plugin, so If I can combine doc installations to minimize shutdowns that would be great My proposal is to define a process for publishing project documentation to the latest Infocenter using these guidelines: - only release docs would be published. This is currently the rule for the main Infocenter as well. No nightly or weekly docs. Too disruptive. - Projects should supply (or make available for public download) the strict minimum plugins needed to run their doc instead of me poking through the plugins directories. - Projects docs would be integrated into the latest Infocenter (3.1 in this case) As an added bonus, project docs added to these infocenters would be indexed by our search engine and, by extension, Google, Yahoo, and everything else. Does this make sense to anyone? D.
This sounds great, and getting projects' help indexed by Google is definitely key. But I'm curious about how this will scale to other projects. Given that BIRT is now under the top-level help which was previously just SDK, it looks like we're moving to the following structure: http://help.eclipse.org/helpXX - sdk - birt - tptp - <other top-level projects> But then do all the Tools and Technology projects get a single infocentre too (e.g. /help/tools and /help/technology)? The main issue I see there is that this lumps together too many unrelated help docs and will have the overloaded feel of MSDN help, which resulting in too many search results unless users define a search scope (which aren't persisted across sessions in the online infocentre). But I'm guessing that this is a smaller inconvenience than the current situation where projects manage their own docs as web pages that might be partially replicated in Help, and do so in inconsistent ways. For the Mylar and AJDT Technology sub projects it seems that the best solution available to us now seems to be to set up our own infocentres on the virtual <project>.eclipse.org servers. Unfortunately approach puts the web administration burden on the projects, forces the projects to learn how to do administer infocentres, and likely means that many projects will be slow to adopt it. But on the plus side it would allow the projects to update the help documentation as often as needed--something I think is critical for rapidly evolving Technology projects. If anyone has a better solution, or if there are plans to have a Technology project infocentre, please let us know.
+1 for consolidating documentation of all Eclipse.org projects. Contrary to what Mik says above, my scope settings were persisted across browser sessions (I guess when running the Eclipse online help locally, the fact that the port number is dynamically computed breaks cookies). And even if later on turns out the amount of documentation books becomes too large for a flat list representation, it could actually be a good opportunity for improving the Eclipse help system itself.
a) Eclipse users can have lots of help plug-ins so it will be good for everyone to see what that looks like. I don't have time (or the need) to install them all locally so this is a good first step. b) "No nightly or weekly docs. Too disruptive" - can you explain why this would be too disruptive? What about Milestone docs? c) Can you get older helps removed from search results? I keep finding the old stuff when I search, for example try running this Google search: http://www.google.com/search?q=IResource+setTeamPrivateMember+setAttributes
(In reply to comment #9) > b) "No nightly or weekly docs. Too disruptive" - can you explain why this would > be too disruptive? What about Milestone docs? I'm no Eclipse expert, but it appears Eclipse needs to be kicked in some form or fashion when plugins are added/removed/changed. 50+ projects at eclipse.org pushing weekly/nightly/milestone changes to Infocenter plugins seems a bit much. > c) Can you get older helps removed from search results? I keep finding the old Ha, our search engine seems to return better results :) http://eclipse.org/search/search.cgi?q=IResource+setTeamPrivateMember+setAttributes&cmd=Search%21&t=All&t=Doc&t=Downloads&wf=574a74 If I try to remove older Infocenters, Konrad scolds me... I would love to remove the 2.1 Infocenter, mind you. Older docs found on, for instance, download.eclipse.org don't belong to me, they belong to the project that published them.
Isn't there a bugzilla open for installing help plug-ins without restarting? If not there should be. For search results, perhaps the old ones could be hidden with a robots file.
Just throwing my two cents in. I don't have an issue with nightly or weekly help updates. I've been writing a book lately and wanted to offer it via a infocenter. I do nightly updates based off some fun shell scripts that fetch the help plugin from a SVN server and restart the info center. I haven't been able to find a way update the help with the infocenter running live. (Actually, I believe there is a way but requires bumping the version number of the help plugin which is unacceptable)
Denis, what format would you want Projects' docs to be in to be published in the InfoCenter? And would this InfoCenter be for user docs alone, or for both user and ISV docs? I assume that it would try to mirror a binary driver, hence only user docs?
(In reply to comment #13) The doc would be the Eclipse plugin that is part of your project (a jar file or .zip file that goes to the plugins/ directory of Eclipse). For instance, I installed Birt on my Eclipse installation and realized it added a plugin for the Help. I took that org.eclipse.birt.doc* directory and put it in the headless Eclipse running at help.eclipse.org. I don't know what an ISV doc is, sorry. D.
Reopening. GEF has been wanting to make its docs available online (and I know other tools like WTP have as well), and this sounds like a good solution.
*** Bug 105840 has been marked as a duplicate of this bug. ***
(In reply to comment #15) Pratik gave me a ZIP file that contains plugins in the eclipse/plugins directory. I unzipped in eclipse's parent directory, kicked Eclipse and Voila ... GEF docs are published online at http://help.eclipse.org/help31 If projects could standardize on, say, putting their plugins in a zip file and maintain the eclipse/plugins/ directory structure within the ZIP, publishing docs to an infocenter could be a self-serve Committer Tools process. D.
Making it self-serve sounds great and the Committer Tools approach would work. Perhaps it's also worth considering having projects standardize on a location to put their help docs that could then be periodically copied over over to the infocentre (e.g. nightly via rsync)? That way we could automate this as a part of our builds. The location could be something like /home/cvs/org.eclipse/www/<project>/help, or perhaps something in the downloads area.
*** Bug 96435 has been marked as a duplicate of this bug. ***
TPTP will contribute its Help docs after TPTP 4.1 has released (planned for mid-November).
WTP would also like to contribute its docs to the infocenter and will do so when WTP 1.0 is released (Dec. 2005).
Closing as Fixed. Live, combined help is now an option. Projects can submit help plugins for inclusion in http://help.eclipse.org/help31, as Birt and GEF have done. The "always up to date" has been addressed by comment 1. D.
