[
https://issues.apache.org/jira/browse/ISIS-1307?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15144498#comment-15144498
]
Dan Haywood commented on ISIS-1307:
-----------------------------------
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.
> Integrating User Help Documentation
> -----------------------------------
>
> Key: ISIS-1307
> URL: https://issues.apache.org/jira/browse/ISIS-1307
> Project: Isis
> Issue Type: Improvement
> Components: Core
> Reporter: Steve Cameron
> Assignee: Dan Haywood
> Priority: Minor
>
> At the moment there is the @PropertyLayout#describedAs() attribute for
> providing help 'hints' to users. I am wondering if there could be added a
> more detailed help information being provide to a user pressing F1 key?
> More specifically to design a mechanism for help documentation to be
> navigated to (into) from the Isis Wicket viewer interface in a context
> sensitive way.
> Broadening this further still, maybe there is a good way to keep user
> documentation embedded within the Java domain object class files and to
> generate formatted user help documents in a similar way that Javadoc is
> generated?
> I've done a little research on this approach but cannot find an example of
> where this has been done, but to my mind it seems natural as a Naked Objects
> way to do it.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
