[Building Sakai] Good example of confusion when using the documentation

Wed Jun 18 06:03:19 PDT 2014

Fwiw, when you go to Confluence, http://confluence.sakaiproject.org, 
look at the Spaces menu in the upper left hand corner. On the Spaces 
page you will see a list of categories which include Contrib and 
Project. You can click on a category to bring up all the spaces tagged 
with that category. Looks like that is fairly well organized. Contrib 
tools show up both as Contrib and Project. However, we have Projects 
that are not Contrib.

I don't disagree that things could be much better. Possibly moving to 
Github will help, but things won't improve overnight. Possibly, using 
Stack Exchange for technical questions will help.

Confluence seems like it will still be needed for a long time and some 
kind of landing spot for documentation will be an ongoing need. 
Therefore, it still may be worth an effort to clean it up. One thing I 
have been wondering is if I should look for macros or just create some 
standards that we can all use when we  come across pages in Confluence. 
We could have three taxonomic divisions: Maintained, Useful - Needs 
updating, Out of Date - consider archiving or deleting. If you go to a 
page that needs updating, or is out of date, it should probably scream 
at you. If it has not been labeled yet, or if it is maintained, it 
probably shouldn't scream at you, but for maintained pages maybe some 
indication that you can look for, that someone has said, yeah, this 
looks good.

Just thinking out loud.

Cheers,
Neal

> Andrew Martin <mailto:andrew.martin at newcastle.ac.uk>
> June 18, 2014 at 7:47 AM
>
> I really hope this is best list for this post, but happy to be 
> complained at if it isn’t….
>
> So I’m trying to create a Newcastle university delta that we apply 
> over the standard vanilla sakai 10 source, this is used by whoever 
> deploys the source on live (we svn the update to keep track of our 
> changes)
>
> I have sakai 10 vanilla source working, I then try to reintegrate the 
> clog tool. Now, I understand the difference between core tools and 
> contrib tools but have never quite understood how all the docs are 
> structured, but I’m chucking myself at this trying to figure out what 
> I do when I figure these things out and more importantly the things I 
> realise along the way (that aren’t super obvious) that I should 
> probably write down and is a good example of how the docs assume you 
> know stuff.
>
> Bear with me on this, I’m using the clog tool as an example, this is 
> really about:
>
> ·The docs
>
> ·The way the docs are structured
>
> ·What is made obvious straight away
>
> ·How I do stuff (the path I take in solving a problem), which I’m 
> /_assuming_/ isn’t that uncommon an approach when you just want to get 
> on with stuff
>
> The problem:
>
> Clog 0.9.3 (used in our old sakai 2.8.x and 2.9.x instances) now 
> doesn’t compile on sakai 10
>
> The infuriating way I got somewhere:
>
> Firstly, I think “damn it, there must be a newer version?”, so I try 
> to find some docs, so (and take careful note here!!) /_the first thing 
> I do is go to *google* and type “sakai clog”_/ which pops up the docs 
> for clog on confluence as the first hit 
> (https://www.google.co.uk/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8#q=sakai%20clog 
> <https://www.google.co.uk/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8#q=sakai%20clog>). 
> The reason why I do this is /_I’ve never been that certain of the best 
> way to find tool information_/, so I click the first google hit 
> https://confluence.sakaiproject.org/display/CLOG/Home
>
> Next I read through the docs trying to find out how the tool is 
> supported and find a link to JIRA under “Issue tracking and feature 
> requests” , so I click through to there and fumble around for a while 
> trying to find something the suggests this tool has a problem with 
> sakai 10, eventually under “road map” I find an issue (clog-111) that 
> is fixed for version 0.9.5 of clog. So next problem, how the heck do I 
> get the source for 0.9.5????
>
> NOTE: In this next bit I’m using various pieces of disparate cobbled 
> together sakai knowledge here, this is an example of “if you didn’t 
> previously know X, Y or Z then you get stuck”!
>
> Much clicking around in JIRA doesn’t turn up much so:
>
> ·I think “I know, let’s go to the svn source site and find the clog 
> tool”, so I skip off to here… https://source.sakaiproject.org/svn/ and 
> scroll around for a bit, NOPE! Wrong.
>
> ·So then I think, “Well, it is a contrib tool, maybe there’s a contrib 
> or tools folder?” NOPE! Wrong.
>
> ·And so I scamper back to the confluence page hoping for a clue, sure 
> enough Adrian has kindly documented where the latest stable and dev 
> source releases are under “Download”, so I click the “trunk” link 
> thinking I can find the latest code
>
> ·Sure enough, I’m plonked straight into the clog tools svn trunk, but 
> then I think “hang on a minute, this isn’t under /svn/ on the source 
> section of sakaiproject, so I navigate up to 
> https://source.sakaiproject.org/contrib/, ahaaaaa, so */_that’s_/* 
> where all contrib tools are kept! NOT on the /svn/ section of the site.
>
> ·So then I think, “why didn’t I know that?? Where does it make this 
> distinction in the documentation? So I scamper off back to 
> confluence’s front page and search for “contrib”
>
> ·First hit is 
> https://confluence.sakaiproject.org/display/~knoop/2007/08/20/Try+Sakai's+Contrib+Tools 
> <https://confluence.sakaiproject.org/display/%7Eknoop/2007/08/20/Try+Sakai%27s+Contrib+Tools>, 
> excellent, a short description of the difference in tools and 
> importantly a link to the contrib svn repository, BUT, this is dated 
> 20/8/2007 (!!) and I can’t find any other sane way to reach this basic 
> snippet of knowledge NOT using search, I would argue this is MEGA 
> important basic stuff that should be part of a “journey of 
> documentation”. I can’t see anything obvious in “General information” 
> or “building sakai” that glues together something as simple as what 
> the difference between core and contrib tools are and that there are 
> two repositories and where they are….
>
> My next thought was then “so I found all the sources, why aren’t the 
> projects more obvious? Why did I feel I had to initially google 
> CLOG?”, here’s what I noticed:
>
> ·Coming back to the JIRA page I noticed there is a projects tab, 
> dropping this down gives me sort of what I need by clicking “view all 
> projects”, using this I can click through into various tools and see 
> how they’re going…. But errrr… where’s the docs????
>
> ·I pop back to the confluence main page and immediately reach for the 
> projects tab…… oh! Errm…. /_There isn’t one!_/
>
> ·Next thing I do is think “well, I started in confluence (via google) 
> so surely docs other than CLOG exist here???, so I use the confluence 
> search to try looking for other tools as an example, sure enough, one 
> after the other, I find every single tool has a nice little page of 
> documentation… which you have to search for??? Why is there not a 
> whacking great “projects” button/link right on the front of confluence????
>
> ·Also I have to wonder if two systems for documentation and issues is 
> the best way? I completely understand the move to git hub, having 
> versioned documentation */_right beside the source and issue trackers_/*
>
> Things I’ve learned:
>
> ·“I” know how to do the above “now”, but it’s highly likely others 
> have struggled and will struggle in a similar way
>
> ·I always start with google unless the docs for a project are strongly 
> functionally focussed on tasks I want to do.
>
> ·Some things are explained but are not as super explicit and in your 
> face as they should be -> a lot of the stuff makes sense but isn’t 
> immediately obvious as an explanation is often stuffed away in ancient 
> posts.
>
> ·Clog tool documentation is reasonably good :) Got me where I wanted 
> to go by concentrating on splitting it up into the tasks I wanted to do
>
> The things that aren’t made mega clear:
>
> ·Svn main source / Contrib svn source and where they are
>
> ·Where are tool docs? -> JIRA has projects drop down, confluence 
> doesn’t?? you have to search
>
> Conclusion:
>
> ·The documentation and source need to be together or closely 
> interlinked and referenced.
>
> ·Lots of people don’t have time to dig through stuff, the best 
> documented projects focus documentation on task/functional based 
> “journeys” through the documentation to get you where you want to go 
> quickly. It’s fine to leave out (i.e. link to) verbose detail as long 
> as the main thrust of the documentation is getting you to a solution.
>
> Andrew
>
> _______________________________________________
> sakai-dev mailing list
> sakai-dev at collab.sakaiproject.org
> http://collab.sakaiproject.org/mailman/listinfo/sakai-dev
>
> TO UNSUBSCRIBE: send email to 
> sakai-dev-unsubscribe at collab.sakaiproject.org with a subject of 
> "unsubscribe"

-- 
Neal Caidin
Sakai Community Coordinator
Apereo Foundation
neal.caidin at apereo.org
Skype me! (but let me know in advance for the first interaction) - nealkdin

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai-dev/attachments/20140618/563df2cc/attachment.html 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: compose-unknown-contact.jpg
Type: image/jpeg
Size: 770 bytes
Desc: not available
Url : http://collab.sakaiproject.org/pipermail/sakai-dev/attachments/20140618/563df2cc/attachment.jpg 