On May 16, 2010, at 8:00 AM, John Fereira wrote: > > > I guess what I'm suggesting is that a uPortal Documentation steward > position doesn't necessarily require a great deal of knowledge about > uPortal but it may require a significant commitment in time to do it > successfully. >
In most successful open-source projects I've seen that are primarily driven by only a few developers, the lead developers are the ones driving the documentation. At times the documentation may get a little out of date, but those are more often those that are or will be less successful. More successful projects seem to usually have clear, easy-to-use, and up-to-date documentation for the latest version of the product. Larger projects that require more work (Apache, Tomcat, ...) have such large communities around them that they can afford to have a whole position or more dedicated to documentation. In smaller projects, just the fact that they are getting their names out there associated with a successful project is enough, and there usually isn't a massive amount to document. uPortal is somewhat between those. There are few resources working on it, like a small project. But it is not a small project when you take into account size of the uPortal codebase, all of the included portlets, integration with CAS etc., and the fact that it is only a framework meant to be customized primarily by university IT departments (for the most part). There may not be a lot of documentation needed to just get up and running (even with Tomcat, a real DB, some types of authN changes, and some light skinning), but to do justice documenting all of the portlets, customizcation, etc. would be a lot of work. A possible plan of action to resolve this issue might be: * Start simplifying the documentation by creating a new wiki space. * Just write a handful of tutorials on (1) step-by-step command-line instructions describing how to download and run the quickstart, (2) step-by-step command-line instructions describing how to set it up in a separate Tomcat instance with a DB (oracle, mysql, etc.), (3) step-by-step command-line instructions describing how to customize authN (remote user/shibboleth authN is fairly easy to setup but not documented well), (4) step-by-step command-line instructions describing how to make some simple skin changes/make your own skin, (5) step-by-step command-line instructions describing how to install other portlets offered by Jasig, and (6) step-by-step command-line instructions describing how to write your own portlets, deploy, and publish them. * Remove all other uPortal content and spaces from the wiki. (Gasp! :) ) * Lead developers and portlet developers must then keep uPortal and portlet documentation up to date with new features as soon as they are released in the most current version. * If possible migration guides for each version of uPortal still offered by Jasig could be created by the lead developer each as its own single page with step-by-step command-line instructions on how to migrate. I know that no page will work for anyone if there are customizations, but if it works for the vanilla version, that is all I think anyone would expect. I know that it was said on the last Jasig call that if the lead developers spent time to clean up the documentation, that means time that is not going into uPortal support and development. However, if someone could just greatly simplify the documentation while making it more practical for the user as well, then perhaps the lead developer and others would be able to maintain it more easily in the same "foolproof step-by-step command-line how to" format. Gary -- You are currently subscribed to [email protected] as: [email protected] To unsubscribe, change settings or access archives, see http://www.ja-sig.org/wiki/display/JSG/uportal-dev
