Vangel- Thanks for the excellent suggestions. We definitely hope to harness the power of the uPortal community to accomplish these goals.
-Jonathan On Sat, May 15, 2010 at 5:45 PM, Vangel V. Ajanovski <[email protected]>wrote: > On 05/13/2010 06:50 PM, Eric Dalquist wrote: > > uPortal experts within the community would fill in those placeholders with > the appropriate content. Our hope with this approach is that the core > uPortal development team can then better focus its documentation efforts on > filling in the information that they are best at while relying on another > person or group to help in the area outside of their expertise, structuring > and organizing the manual content. > > From a deployers view, I think that I should tell that with uPortal 3 > manual everything looks better and more clear and better organized than the > case was in 2004-5 when I first started with it. So it definitely seems it > is going in a better direction. But the wiki space is (looks) the same, with > many documents that noone knows if they are relevant or not. > > So, I have a small suggestion for a possible way to do better, no matter > who will do it. > Supposedly uPortal has a pretty large university community. So, involve the > community. More! > Start by sending this message on the users list (I have not seen it there). > > The manual is a good start for someone who is just ... starting. And I > think that as it is, that's good enough to get arround to start with the > quickstart, configure basic things like authentication, database, or start > from source up to a basic portal. But really, really good documention set > for things that are a bit more special is lacking. In the previous years I > have scooped information from powerpoint slides, blogs, mailing lists and > scattered wiki pages. Wiki pages seemed least helpful because it was never > clear for which version of uPortal were they intended and in which version > they indeed worked. That was not good and should be addressed. > > So, I think that a good start for doing that is to start from scratch with > the wiki and do two main pages. > Main page for total beginners and advanced main page for advanced users who > were finally able to start it all up, worked with it a bit and want to > customize something special. > > The page for total beginners should have clear links with big letters to > separate administrator and user guides. > > The advanced page should have a map or an index of all the possible topics > or all possible features of uPortal. But I really mean all the possible and > not just the ones that are documented. Of course this can only be done from > scratch by developers, because they are the only who know what types of > tricks and tips would be possible. Whan kind of customizations would be > possible, etc... > > Then, it should be left to the whole community and not just the developers > to write it and fill it with information. Do it the classical Wiki way. > > The next step would be to invite the whole community to fill in the pages > behind bullets. By "fill in" I mean either put a few notes as to where to > look for information, or just a comment that if this is not documented or > not clear - one should ask on the mailing list, or try to document how one > has achieved that. I really think that if you constantly invite and ask the > community for help, the whole thing will start and once it is started, the > community will rise. > > By constant invites, I mean inviting (with big letters) on the site on > every page and also with messages sent to users on the mailing lists > regularly. How? Well take a practice that whener someone asks a question and > this question was solver, one should invite this person to try to fill a > document on the wiki what has he done, or what was wrong on the wiki or what > was misplaced etc. > The clue is to get everyone motivated to share the information they know. > > Then the role of the otherwise too busy developers would be just to just > sometimes click "Agree" on the written docs (and thereby endorse them as > official document) or modify bits and pieces or put just a note that this > definitely works on uPortal x.x.x. > > This way the one(s) responsible for the content organization will be > required to just monitor the mailing lists for possible new features or > topics that are worth documenting, monitor for spam and abuse, and from time > to time send out motivational emails why documenting things is good. > > I would apply for this, I will be doing transition to 3.x this summer and I > will have to document everything I do. So if I have to document it anyway, > why wouldn't I document it in public... right? > I think this approach could work if everyone that did something useful or > special would share the documentation. > > I don't think I have the right knowledge to start and organize the whole > effort, but I am willing to help and share what I can. > > -- > > 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 > > -- 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
