Community
Participate
Working Groups
We (the Foundation) have too many places for committers to try to find documentation. We should have a single "documentation entry point" the same way we have a single "process entry point" (the portal). At the very least, this single DOPE (Documentation Entry PointE) should have an FAQ that points to other documentation should the other documentation need to be stored elsewhere. The committers currently have these starting places: http://www.eclipse.org/projects/ that leads to all sorts of hard to find pages including: http://www.eclipse.org/projects/dev_process/index.php http://www.eclipse.org/projects/dev_process/project-status-infrastructure.php http://wiki.eclipse.org/index.php/Development_Resources http://wiki.eclipse.org/index.php/Phoenix_Documentation http://www.eclipse.org/org/documents/ I suggest to us (and thence to me, who will be doing the work) that create a single DOPE and redirect all the other pages to it. For ease of editing, I suggest the wiki page http://wiki.eclipse.org/index.php/Development_Resources I will move these pages: http://www.eclipse.org/projects/dev_process/index-quick.php http://www.eclipse.org/projects/dev_process/* (including all the guidelines pages, but not "the official dev process" page I convert the http://wiki.eclipse.org/index.php/Development_Resources page into a FAQ divided by topic: project website project wiki project information pages including project activity/commits explorer and timeline committers: adding, removing starting a new project creating a release IP process and legal files ...? I will add a "file a bug" link to every documentation page that I can affect. I will also add a "what generates this page" to all generated pages that I can affect.
I will also add a link from the portal the DOPE and vice versa. Using wiki pages will allow the community to help (people like Nick and Ed and Martin are sure to assist). In return, the Foundation staff has to make sure that we update these pages each time we modify the some piece of infrastructure. I will add a comment to the meta-data code to remind us to do so.
Great idea. We need this. Once you have the skeleton set up, I will move: - Phoenix documentation @ http://eclipse.org/phoenix, as its target is committers - Phoenix documentation @ http://wiki.eclipse.org/Phoenix - Committer Tools docs @ https://dev.eclipse.org/committers - Committer-related content on http://wiki.eclipse.org/Webmaster_FAQ We could perhaps add Servers and Infrastructure to the list of FAQ topics?
I'm in. Suggest instead of one massive DOPE you use pages with an implied hierarchy in the name (where appropriate for the length of content), eg: wiki.eclipse.org/Development_Resources/FAQs wiki.eclipse.org/Development_Resources/FAQs/Project_Website wiki.eclipse.org/Development_Resources/FAQs/Project_Wiki wiki.eclipse.org/Development_Resources/FAQs/Project_Information_Pages wiki.eclipse.org/Development_Resources/FAQs/Project_Creation wiki.eclipse.org/Development_Resources/FAQs/Project_Release wiki.eclipse.org/Development_Resources/FAQs/Project_Legal_Whatsit wiki.eclipse.org/Development_Resources/HOWTOs/Jar_Signing wiki.eclipse.org/Development_Resources/HOWTOs/Using_The_Portal And of course you'll want a new [[Category:Development_Resources]] to contain all these pages in one "documentation portal". Then, if you shorten the current Development_Resources page and migrate that content INTO the category page, it can serve as header for that page, underneath which you'd have an ever-expanding generated category list of pages. (Finally, you'd want to move the existing page to point to the category page.) Here's a sample of how a category-as-portal (aka DOPE) can work: http://wiki.eclipse.org/Web_Tools_Project
I know I've mentioned this before, but it might be a good time to investigate the Eclipse Process Framework for documenting this. I posted a message in the EPF newsgroup, and there was some slight interest from there to see this done. It would of course mean learning how to use the tool, and to generate a Website or page from it, but at least the information would be kept in one place. Besides eclipse should leverage it's own projects when it can, and they fit the need.
(In reply to comment #4) > I know I've mentioned this before, By all means, go for it! I've said before that if you produce the files, I'll put them in place on the website.
(In reply to comment #5) > (In reply to comment #4) > > I know I've mentioned this before, > > By all means, go for it! I've said before that if you produce the files, I'll > put them in place on the website. > Actually, I was hoping for a joint or community effort instead of just making one person do it. If we need to make it an official project proposal then we should do it. I think it's too big of a task for one person to do.
(In reply to comment #6) > Actually, I was hoping for a joint or community effort instead of just making > one person do it. That's be great too. Start with a project proposal, perhaps, to gather the core team together...?
From Denis: >> - Phoenix documentation @ http://eclipse.org/phoenix, as its target is >> committers /cvsroot/org.eclipse/www/phoenix/development.php is the only one there >> - Phoenix documentation @ http://wiki.eclipse.org/Phoenix This is already on the Wiki, so it may only need to be moved/annotated/etc. >> - Committer Tools docs @ https://dev.eclipse.org/committers /cvsroot/org.eclipse/dev/committers/help/inc (all except status.php) and >> - Committer-related content on http://wiki.eclipse.org/Webmaster_FAQ Again, this is already on the Wiki, so it may only need to be moved/annotated/etc.
Well, the documentation has all (98%) been moved to the wiki http://wiki.eclipse.org/Development_Resources so that everyone can participate in arranging it into a more logical structure. I believe that this will be a continuous process, perhaps even an endless process of defense against docu-rot, but I'll keep at it (and I'm sure others will as well). In the meantime, I'm going to mark this bug as fixed.
Thanks, Bjorn. Having the IT/web docs in the Wiki just makes it easier (therefore, more appealing) for me to update.
