You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@isis.apache.org by Stephen Cameron <st...@gmail.com> on 2016/02/12 06:03:02 UTC
'Generating' User Help Documentation
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
Re: 'Generating' User Help Documentation
Posted by Stephen Cameron <st...@gmail.com>.
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 <da...@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 <st...@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.62@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.62@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.62@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
> > >>>
> > >>>
> > >>>
> > >>
> > >
> >
>
Re: 'Generating' User Help Documentation
Posted by Dan Haywood <da...@haywood-associates.co.uk>.
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 <st...@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.62@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.62@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.62@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
> >>>
> >>>
> >>>
> >>
> >
>
Re: 'Generating' User Help Documentation
Posted by Stephen Cameron <st...@gmail.com>.
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.62@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.62@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.62@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
>>>
>>>
>>>
>>
>
Re: 'Generating' User Help Documentation
Posted by Stephen Cameron <st...@gmail.com>.
Clarification: it reads JavaDoc comments, like the standard JavaDoc Doclet.
On Fri, Feb 12, 2016 at 5:26 PM, Stephen Cameron <steve.cameron.62@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.62@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
>>
>>
>>
>
Re: 'Generating' User Help Documentation
Posted by Stephen Cameron <st...@gmail.com>.
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.62@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
>
>
>