Grouper Users - Open Discussion List

[Richard James <>]

Hi,

Below are a few pieces of feedback with regards to the documentation for 
Grouper.

From a technical perspective, the documentation is in the main very good, 
documenting the required commands in a clear and structured manner and 
providing an example of how to implement the functionality. In particular I 
believe the documentation for the initial installation and configuration of 
Grouper is very simple to follow and allows you to start getting to grasp 
with Grouper very quickly. 

For the different functionality, from looking at the documentation that is 
available it can sometimes be quite difficult to immediately put into context 
what the functionality can achieve, i.e. what you can achieve with the use of 
the attribute framework. It can sometimes take a bit of searching around the 
site, including mailing lists, to build up a picture of what the 
functionality can provide. Therefore I think it would be beneficial to link 
through to use cases from the "technical pages", to either "implemented" or 
"what it could achieve" use cases, which would hopefully provide the form of 
context that is required. 

There are certain areas where this is already well done, for example with the 
Grouper Loader it documents the technical perspectives of the loader, but 
then goes that step further and shows how it can be used to loader an 
organisational structure into Grouper. 

From a finding things perspective on the wiki, sometimes the documentation 
for functionality can be quite difficult to come across unless you have a 
good idea of what you're looking for. I tend to just use the search function 
to find what I'm looking for now rather than using the links on the landing 
page. The contributions made by other institutions are also a very useful 
feature to have, yet they aren't predominately displayed when you first 
arrive on the documentation page. I think with a little tinkering of the 
navigation of the wiki this could easily be fixed.

One of the most useful features of the Grouper website is most definitely the 
mailing list, and I think it could be beneficial to link this into the Wiki 
in some capacity. There could be some kind of feedback channel to the wiki, 
sometimes a resolution to a common query/issue is documented within the 
mailing list, but the wiki sometimes has no reference to the fact this has 
been resolved. Possibly having a troubleshooting area which documents some of 
the discussions and resolutions/approaches on the wiki could be quite useful. 

At Newcastle University we would be very happy to contribute towards 
providing use cases for the wiki, as part of our current project the creation 
of use cases is one of the main project outcomes, and we would be more than 
happy to feed these into the Grouper community. Also as part of the project 
we will be producing a series of videos/screen captures will show how Grouper 
can be used to in different use cases. We would be more than willing to share 
these with the community, and from a personal perspective find the use of 
these kind of videos very useful (in particular the series of videos Chris 
Hyzer has provided for certain areas of Grouper).

Mainly I have had positive experiences of the grouper documentation and have 
been able to find what I was looking for through a combination of the wiki 
and the mailing list, I think with a few adjustments it could be even more 
useful. I hope the above is of some help, and we would be happy to contribute 
with use cases or provide further feedback through the redevelopment of the 
documentation.

Regards

Richie James
ISS Middleware Team
Newcastle University UK

>-----Original Message-----
>From: Tom Barton 
>[mailto:]
>Sent: 26 May 2010 21:15
>To: 
>
>Cc: Ann Kitalong-Will
>Subject: [grouper-users] feedback on grouper documentation
>
>Have you had a recent experience with needing to rely on grouper's
>documentation for some purpose, and either couldn't find something you
>needed or wish it would have been much easier to learn?
>
>We will take an initial step to rework the grouper documentation wiki
>over the next 3 months, and we'd very much like your feedback, positive
>and negative, to help us identify the documentation needs we should
>focus on. Our motivation is to make it easier for implementers and
>others to find the information they need to help them with specific
>tasks, such as installing, upgrading, or troubleshooting.
>
>Ann Kitalong-Will, who supports some of the other Internet2 working
>groups, will guide this effort. AnnKW will engage with the grouper
>community on this list for this project.
>
>So please do share your experience with us. We'd also be extremely
>grateful if one or two of you would be willing to work more closely with
>us as "documentation use case experts" to help us ensure that the
>reworked documentation is effective for your use case. Please contact
>AnnKW if you'd like to inquire about working with us in this capacity.
>
>Thanks!
>Tom Barton
>on behalf of the grouper team