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 > >>> > >>> > >>> > >> > > >
