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

[Andrew Martin]

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). 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, 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai-dev/attachments/20140618/8927abd1/attachment.html