Hi Dan, "outside the code - but close to it" does seem like a better solution, asciidoc and markdown do seem to have become a defacto standards. (No one was ever meant to write XML directly).
It seems there are tools that go from asciidoc to DocBook as well [2], if that is is specific interest for creation of true documents. The overlay idea is good too, I was thinking of something like in Eclipse where you can then press 'F2 for focus' to scroll in the overlay dialog. [2] http://asciidocfx.com/ On Fri, Feb 12, 2016 at 10:53 PM, Dan Haywood <d...@haywood-associates.co.uk> wrote: > Hi Stephen, > > I'm not certain about the idea of using Javadoc; I think that documentation > tends to be more focussed for developers reading the code rather than > end-users. > > My own thoughts on the idea was - rather as we have the supplementary > Xxx.layout.json file - to also have an optional Xxx.md or Xxx.adoc to > contain appropriate documentation in either Markdown or Asciidoc. Hitting > F1 could bring that page up nicely formatted as some sort of overlay (same > as how hitting "?" in gmail or similar brings up an overlay there). > > Moving this documentation outside of the code - but close to it - would > means that writing this documentation could be handed off to a technical > writer (for those larger teams that have such a luxury). A bit like how we > externalized i18n into the .po files. > > What we could also do, perhaps, is add a new goal to the isis-maven-plugin > to automatically generate a stub for these files; perhaps with sections for > each of the properties/actions/collections. > > I'll add all the above to the ticket you raised... > > Cheers > Dan > > > > On 12 February 2016 at 11:22, Stephen Cameron <steve.cameron...@gmail.com> > wrote: > > > Well all I can say so far is that in the process of trying to create good > > user documentation I am hitting a problem of lack of good user > > documentation. > > > > I think the concept of Javadoc to Docbook XML via a doclet is good, I got > > dbdoclet to do that from the command-line, but there is a java exe > > associate with dbdoclet called Dodo that should allow me to do the whole > > transformation chain, XXX.java -> DocBook XML -> (HTML,PDF,...). That is > a > > bit cryptic at the moment. > > > > Ultimately it should be just a maven plugin too, so to be useful as a > > general approach in Apache Isis will take some work. So Plan B for now. > > > > > > > > On Fri, Feb 12, 2016 at 5:27 PM, Stephen Cameron < > > steve.cameron...@gmail.com > > > wrote: > > > > > Clarification: it reads JavaDoc comments, like the standard JavaDoc > > Doclet. > > > > > > On Fri, Feb 12, 2016 at 5:26 PM, Stephen Cameron < > > > steve.cameron...@gmail.com> wrote: > > > > > >> Here is something that is maybe close to what I am thinking of, > dbdoclet > > >> [1]. It converts JavaDoc to DocBook, I'd then manually edit the > DocBook > > XML > > >> to just preserve the user relevent bits which I think will be the > first > > >> part of the class comment and any comments on public methods and > > properties > > >> that are visible to the user in the viewer. > > >> > > >> [1] http://www.dbdoclet.org/ > > >> > > >> On Fri, Feb 12, 2016 at 4:03 PM, Stephen Cameron < > > >> steve.cameron...@gmail.com> wrote: > > >> > > >>> Hi all, > > >>> > > >>> I just added an issue to Jira suggesting enhanced user help > > >>> documentation via the F1 key or some other means [1](system user as > > opposed > > >>> to system developer). > > >>> > > >>> There is a bigger question in my mind about how user documentation > gets > > >>> created - as a process - that is maybe worthy of discussion. > > Specifically, > > >>> the idea that in an DDD and Naked Objects project such documentation > > should > > >>> be created at the same time that code is written and maybe even be > > embedded > > >>> within code in some way. > > >>> > > >>> In most projects I see the user documentation (if there is any) as > > being > > >>> relevent to developers, certainly that is the way its done with the > > Apache > > >>> Isis demo projects and Add-ons, where the Github README files are > basic > > >>> explanations of the functionality and how its acheived in code. So > the > > user > > >>> documenation is an initial subset of the developer/maintainer > > >>> documentation. Another way to look at it is that the user > > doccumentation is > > >>> useful to explain the models 'ubiquitous language' both to new > > developers > > >>> and to users. > > >>> > > >>> Maybe there is a way to process the code and embedded comments to > > >>> generate user documentation that could actually work in an Apache > Isis > > >>> project, given the close relationship between class and methods and > > what > > >>> the user sees? > > >>> > > >>> I see that if you add any tags, not only HTML tags to comments then > > >>> Javadoc preserves them, that would suggest that a customised Doclet > > might > > >>> work as a means to achieve this. I like this general idea, given the > > recent > > >>> discussion of adding UML diagrams to Javadoc. Maybe the idea of an > > specific > > >>> Apache Isis Project doclet (or doclets) makes sense? > > >>> > > >>> You can select a custom doclet in Eclipse, but I have no experience > as > > >>> yet in creating one. > > >>> > > >>> On the other hand, people seem happy with Asciidoc, and I will give > > that > > >>> a try in the short term. > > >>> > > >>> Regards > > >>> Steve Cameron > > >>> > > >>> > > >>> [1]https://issues.apache.org/jira/browse/ISIS-1307 > > >>> > > >>> > > >>> > > >> > > > > > >
