I've been thinking that documentation is one area that I can maybe make a small contribution to the project. Asciidoc is probably quite good, seems so from the slides. A reinvention of similar things but with a specific focus. [XML or rather SGML was invented for exactly this purpose, why IDEs haven't taken this on board like Word processors is baffling to me, no one ever intended people to hand craft complex markup, but HTML changed that I guess, to make use of simple text editors]
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. 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. Maybe you have thoughts of another book Dan & Jeroen, 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. 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 > > > > > >
