On 6 December 2015 at 21:59, Stephen Cameron <[email protected]> wrote:
> I've been thinking that documentation is one area that I can maybe make a > small contribution to the project. That'd be great. > Asciidoc is probably quite good, seems > so from the slides. Yes, I'm a fan. Related, I've been thinking it would probably be good to design a 1 or 2 > day course in use of Apache Isis, make it self-guided, but also something > that could be used for actual courses to make a few dollars. Might help > with adoption too. The course notes and the general documentation would be > integrated. > > We do have some tutorials on our website [1], it might be sufficient to ensure that these are up-to-date. I was also thinking of doing a series of 5-minute screencasts that might go together to create a single extended demo. > The simple archetype is good, but I am suggesting that structured learning > is good too. > > Probably cannot avoid the project committers writing the general > documentation, but a course is something else perhaps. > I see the course as being gentle way for not so experienced people (lke me) > to be eased into the way of thinking behind Isis. In taking it up you do > tend to become focused on specific aspects and miss out on others (usually > by rushing into a project). So help in really getting an understanding of > the breadth early on would be good, I am now trying to do that properly > after many months. Also, observing new adoptees in a course situation > provides a fast feedback loop. > > I'm definitely not against having some courseware on Apache Isis. As with all these things, it's not been a priority (for me at least) because there's not been any requirement; also I could probably just a teach such a course off the top of my head. But I wouldn't say no to there being some open source courseware to help spread the word. > Maybe you have thoughts of another book Dan & Jeroen, Never again! Well, maybe a mini-book one of these days... > but management types > who have to evaluate adoption risks maybe would go for a course more than a > book. Of course both are possible and reinforcing. > > > Perhaps, though I'm not certain that the existence of a course would help "management types" think that adoption risk was lower... the existence of two books on the topic (Richard Pawson's, and mine) hasn't exactly made any difference. That said, if you want to collaborate (probably off-list) on putting together a course, then I'm happy to be involved. Cheers Dan [1] http://isis.apache.org/guides/tg.html > > On Mon, Dec 7, 2015 at 1:03 AM, Dan Haywood <[email protected]> > wrote: > > > On 4 December 2015 at 22:38, Stephen Cameron <[email protected] > > > > wrote: > > > > > Thanks Dan, It was getting a bit too big I agree. Ideally something > like > > > the Eclipse help would be better for long term maintenance I guess, but > > > that requires a server backend. > > > > > > > > It's written in Asciidoc, which opens up lots of publishing methods. At > > some point I will get around to generating downloadable PDFs, for > example. > > > > Doesn't look like Eclipse help is an output, but there's a fairly rich > > toolchain, see eg slide 13 of [1] > > > > > > [1] > > > > > http://mgreau.com/posts/2015/06/22/asciidoc-create-and-publish-everywhere-from-anywhere.html > > > > > > > > > > > On Sat, Dec 5, 2015 at 5:24 AM, Dan Haywood < > > [email protected]> > > > wrote: > > > > > > > Hi folks, > > > > > > > > Just a heads-up to say that I've spent a happy day (not really) > > splitting > > > > out and slightly reorganizing our documentation. > > > > > > > > The user guide and reference guide were rather too large, so have > both > > > been > > > > broken up; the user guide is now in six parts: > > > > > > > > - fundamentals > > > > - wicket viewer > > > > - restful objects viewer > > > > - security > > > > - testing > > > > - beyond the basics > > > > > > > > while the reference guide is in four: > > > > > > > > - annotations > > > > - domain services > > > > - configuration properties > > > > - classes, methods, schema > > > > > > > > The layout stuff and the web.xml stuff that was in the old ref guide > is > > > now > > > > in fundamentals and "beyond the basics", respectively. > > > > > > > > These are all referenced from our documentation page [1] > > > > > > > > My apologies; any bookmarks you might have had for the old > > user/reference > > > > guides will be broken. I couldn't find a way to cook this particular > > > > omelette without breaking some eggs. > > > > > > > > But hopefully the guides will now be easier to grok and to use. > > > > > > > > Feedback welcome, as ever > > > > > > > > Cheers > > > > Dan > > > > > > > > [1] http://isis.apache.org/documentation.html > > > > > > > > > >
