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 <[email protected] > wrote: > Clarification: it reads JavaDoc comments, like the standard JavaDoc Doclet. > > On Fri, Feb 12, 2016 at 5:26 PM, Stephen Cameron < > [email protected]> 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 < >> [email protected]> 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 >>> >>> >>> >> >
