Re: [uportal-dev] Documentation Steward

[Vangel V. Ajanovski]

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 uportal-dev@lists.ja-sig.org as: arch...@mail-archive.com To unsubscribe, change settings or access archives, see http://www.ja-sig.org/wiki/display/JSG/uportal-dev