I think one approach that would be useful would be to start with use cases - or use case scenarios. Consider these as chances to tell the new user what objects he or she would encounter in doing simple things like setting up a data ingest script or setting up a workflow or finding a file or set of files. What are the user interfaces that person would encounter? Which pieces of the system would be behind them? What is the message dialog that those pieces have to orchestrate? At least from my point of view, I need a structural view of the pieces, including the assumed directory structure for the code and for the data. Without that structural view, the system is "without form and void. Darkness covers it."
Bruce B. On Mon, Apr 14, 2014 at 8:48 AM, Bruce Barkstrom <[email protected]>wrote: > There's a brief Viewpoint article in the new issue of CACM that > may be worth thinking about: Neville-Neil, G. V., 2014: Kode Vicious: > This is the Foo Field: The meaning of bits and avoiding upgrade > bogdowns, CACM, Vol. 57, No. 04 (Apr, 2014), pp. 30-31. > > It begins with a query from "Confoosed": "When will someone > write documentation that tells you what the bits mean rather > than what they set. ..." The response notes "The problem ... > is assumed knowledge. Most engineers, of both the hardware > and software persuasion, seem to assume the people they > are writing the documentation for -- if they are writing documentation > at all -- already have the full context of the widget they are working on > in their heads when they start to read the docs. The documentation > in this case is a reference, not a guide. If you already know what you > need to know, then you are using a reference; if you do not know > what you need to know, then you need a guide." > > In other words, if the documentation is a collection of man pages, > it's a reference, not a guide. New users need a guide - with examples > they can try and verify if the system is working. Getting the > configuration > to work with proper paths is critical - and can be a major part of the > initial learning curve. > > Bruce R. Barkstrom > > > > On Mon, Apr 14, 2014 at 7:29 AM, Lewis John Mcgibbney < > [email protected]> wrote: > >> Hi Tom, >> There is actually some low hanging fruit here as well. >> Simplifying the site is a no brainer tbh. This just takes a late night or >> two and some steely determination from one or two individuals. >> Moving site documentation out of trunk and onto a wiki/website that can be >> edited in an adhoc manner is a much more logic solution than we currently >> have. >> Getting a (possibly RADIX) service up and running which can be hosted at >> Apache VM is a no brainer as well. Your UI stuff will come in extremely >> handy here. >> Getting the build stabalized for *nix systems is a must. Windows build is >> equally important but we need someone to take this on. From what I can >> see, >> lots of this has to do with the configuration files not being found on >> paths etc. This may or may not take as long to fix as initially imagined. >> For the time being I've disabled unsuccessful messages for the Windows >> build coming to the dev list as it was starting to make me depressed again >> :) >> I'm going to begin work on OODT-670 which will hopefully stabalize builds >> on *nix however this is rather non-trivial so may take it bit of time. >> I'll >> try my best. >> This is all from me right now Tom. I've got a clear idea of what I *think* >> we should do. Maybe getting a roadmap together on the wiki would be a good >> goal. >> Within the above scope, we could maybe push a 0.7 release as there have >> been a number of issues addressed? >> >> >> >> >> On Mon, Apr 14, 2014 at 8:39 AM, Tom Barber <[email protected]> >> wrote: >> >> > I'll move this over here as it does carry some relevance ;) >> > >> > Me and Lewis were discussing OODT over the week and a couple of take >> aways >> > we saw that were hindering adoption was a) The name (but we can't do >> much >> > about that ;) ) >> > b) The website >> > c) The build >> > >> > So a couple of things I would like to work on on top of the Tika update >> > and fixing the GMT build is getting the default config to build out of >> the >> > box, because currently you have to tweak the properties files and this >> > makes life real hard for people just wanting to get started. >> Personally, I >> > think that if you don't have a build that compiles without changes at >> > checkout, either you have to change it or make it stupidly easily for >> > people to understand what needs setting, because otherwise they get >> > lost/bored and go do something else. Also it makes life easier for >> people >> > trying to understand whats broken in the codebase(failing tests due to >> code >> > problems) and whats broken because of configuration issues(failing tests >> > due to user problems) which is currently far from clear. >> > >> > Lastly, at some point over the next few months I'd like to take a stab >> at >> > creating an alternative website that tries to hide some of the science >> > stuff and all the tailored build pages and make it clearer where the >> useful >> > information was and what the platform does to no science type people. >> > >> > Clearly both these projects are purely hypothetical and I wont push >> > anything without sign off, but there was a decent turn out to my talk >> and >> > some cross over with people who knew BI, so I think its an angle worth >> > pursuing. >> > >> > Comments and suggestions please :) >> > >> > Tom >> > >> > >> > On 14/04/14 02:31, Mattmann, Chris A (3980) wrote: >> > >> >> Scoff unlike OODT yeesh >> >> >> >> Sent from my iPhone >> >> >> >> On Apr 13, 2014, at 4:43 PM, "Tom Barber" <[email protected]> >> >>> wrote: >> >>> >> >>> Alright then chaps, >> >>> >> >>> After too much beer i've got home and checked out the source. It even >> >>> compiles without hacking stuff unlike OODT which is always nice. So, >> for >> >>> someone that doesn't use Gora or have any knowledge of the code base, >> if I >> >>> want to help hows best to get started? :) >> >>> >> >>> Cheers >> >>> >> >>> Tom >> >>> -- >> >>> *Tom Barber* | Technical Director >> >>> >> >>> meteorite bi >> >>> *T:* +44 20 8133 3730 >> >>> *W:* www.meteorite.bi | *Skype:* meteorite.consulting >> >>> *A:* Surrey Technology Centre, Surrey Research Park, Guildford, GU2 >> 7YG, >> >>> UK >> >>> >> >> >> > >> > -- >> > *Tom Barber* | Technical Director >> > >> > meteorite bi >> > *T:* +44 20 8133 3730 >> > *W:* www.meteorite.bi | *Skype:* meteorite.consulting >> > *A:* Surrey Technology Centre, Surrey Research Park, Guildford, GU2 >> 7YG, UK >> > >> >> >> >> -- >> *Lewis* >> > >
