Hi Taher
Thanks for summarising the main points and also proposing a potential way
forward.
I'd be happy with this solution and I really like the fact that we could
incorporate any AsciiDoc contributions too.
+1 from me
Thanks
Sharan
On 2017-06-12 23:55 (+0200), Taher Alkhateeb
wrote:
> Hi Michael, Sharan, All
>
> Reading through your posts flicks a few light bulbs. I think more or less
> we can summarize the highlights:
> - It's useful to have two sources of documentation: Long documentation in
> the wiki and short functional documentation inside the code base
> - Sharan prefers to keep DocBook (me too!) as this provides the least
> amount of work compared to building from scratch a new solution.
> - Michael prefers to minimize the the sources of documentation (me too!) to
> focus efforts and ease contribution.
>
> To try and focus this thread, may I suggest that we proceed as follows:
> - If everyone agrees on keeping DocBook, we can create a new JIRA to fix
> the implementation (I can try to help out, volunteers are more than
> welcomed)
> - We create a second JIRA that depends on completing the above JIRA for
> inclusion of the webhelp component. It might need to be reimplemented in a
> cleaner, more efficient way.
> - We accept AsciiDoc contributions from users subject to converting them to
> DocBook before inclusion in the code base (either committer or contributor
> can use the conversion tools).
> - We go ahead and proceed with the documentation update plan including the
> latest thread by Michael on how to cleanup the wiki and initiatives by
> Sharan to cleanup the documentation in the code base.
>
> WDYT?
>
> Cheers,
>
> Taher
>
> On Mon, Jun 12, 2017 at 1:07 PM, Michael Brohl
> wrote:
>
> > Hi Sharan,
> >
> > see my remarks inline...
> >
> > Regards,
> >
> > Michael
> >
> > Am 12.06.17 um 11:09 schrieb Sharan Foga:
> >
> >> Hi All
> >>
> >> I think the issue we have with documentation is a complex one and I don't
> >> think that all the different types of documentation that we need for OFBiz
> >> could all reside within the codebase at this stage. Perhaps in the future,
> >> though it depends on how our existing documentation effort evolves.
> >>
> >
> > I agree that we should not only focus on documentation in the code. That
> > would be approach well suited for a more technical project like Freemarker.
> > We have to provide a good technical documentation PLUS a good user
> > documentation for the functional part, describing business processes, how
> > to configure them etc.
> >
> > The latest questions in the user list clearly show that we need more
> > how-to... documentation and easy entry points for users to find that
> > documentation.
> >
> > So I thin we need:
> >
> > * a good Javadoc and surrounding technical documentation for developers
> > * a good business process description, how-tos and examples
> > * a context-related help inside OFBiz (maybe also with language support)
> > * a general high-level overview of the features OFBiz and it's plugins
> > provides (managament summary, marketing overview)
> >
> > It would be great if we could form some named teams to take care of this
> > and who continuously work on it.
> >
> >
> >> See link the the email I sent a couple of weeks ago about how we are
> >> planning to work on structuring our documentation effort.
> >>
> >> https://s.apache.org/tmMX
> >>
> >> We are working on multiple documentation channels and need to focus on
> >> writing, reviewing and generating the content because without the content
> >> ââ¬â we won't have anything and currently Confluence can fulfill most
> >> of
> >> these channels.
> >>
> >> At this stage for me this discussion is primarily concerned with
> >> implementing something that will manage our End User Menu Structured
> >> Documentation within the OFBiz applications. This is something we can't
> >> effectively do (or would want to do in ) Confluence. We already have
> >> content available to update some of this but it has been on hold pending
> >> this discussion and decision on the technology.
> >>
> >> At the moment within OFBiz, we have some limited screen and application
> >> help which I think we need to keep and improve. This is help that appears
> >> when someone is on a screen or within an application, and they they can
> >> click the help button.
> >>
> >
> > I think the best approach would be to provide a good structured, release
> > specific documentation which we can generate to multiple output formats
> > like html and pdf (see Camel).
> > If we manage to somehow index the html help (url and anchors) we could
> > simply save the link/anchor in the webhelp content and serve it either from
> > the official web page or put it in the project.
> >
> > That would kill two birds with one stone.
> >
> > Because of it's complexity I would strongly suggest to have as few as
> > possible sources of documentation.
> >
> > In the past we have had 2 contributor efforts to correc
