Notes from Apachecon EU Budapest Meeting

[Sharan-F]

Hi Everyone

Please see below for the link to the notes from the meeting we held at Apacheon in Budapest last week.

https://cwiki.apache.org/confluence/display/OFBIZ/Apachecon+Workshop%3A+19th+November+2014

A key point to remember is that no decisions were made and that these are just the notes from our discussions.

As you will see, a lot of ideas/proposals came up that need community feedback, discussion and opinion.

Please feel free to provide any feedback or comments using this mailing list thread.

Thanks
Sharan

[Todd Thorner]

Quick opinions on the rough ideas...

1. Turn the "kernel" into something based around containers (e.g.
docker).  This approach could also apply to many dev-ops considerations
that are internal to the project.
2. Make DITA the basis of all documentation.



On 14-11-26 04:13 AM, Sharan-F wrote:

> Hi Everyone
>
> Please see below for the link to the notes from the meeting we held at
> Apacheon in Budapest last week.
>
> https://cwiki.apache.org/confluence/display/OFBIZ/Apachecon+Workshop%3A+19th+November+2014
> <https://cwiki.apache.org/confluence/display/OFBIZ/Apachecon+Workshop%3A+19th+November+2014>  
>
> A key point to remember is that no decisions were made and that these are
> just the notes from our discussions.
>
> As you will see, a lot of ideas/proposals came up that need community
> feedback, discussion and opinion.
>
> Please feel free to provide any feedback or comments using this mailing list
> thread.
>
> Thanks
> Sharan
>
>
>
> --
> View this message in context: http://ofbiz.135035.n4.nabble.com/Notes-from-Apachecon-EU-Budapest-Meeting-tp4658991.html
> Sent from the OFBiz - User mailing list archive at Nabble.com.
>

[Pierre Smits]

Todd, all,

Don't you just love those acronyms.... What is meant by that (DITA)?
Remember, the audience is diverse.

DITA as opposed to PITA?

Al jokes apart. Documentation is important with respect to adoption. From
all angles: business, development, deployment/implementation, etc.

Regards,

Pierre Smits

*ORRTIZ.COM <http://www.orrtiz.com>*
Services & Solutions for Cloud-
Based Manufacturing, Professional
Services and Retail & Trade
http://www.orrtiz.com

On Wed, Nov 26, 2014 at 4:11 PM, Todd Thorner <[hidden email]>
wrote:

> Quick opinions on the rough ideas...
>
> 1. Turn the "kernel" into something based around containers (e.g.
> docker).  This approach could also apply to many dev-ops considerations
> that are internal to the project.
> 2. Make DITA the basis of all documentation.
>
>
>
> On 14-11-26 04:13 AM, Sharan-F wrote:
> > Hi Everyone
> >
> > Please see below for the link to the notes from the meeting we held at
> > Apacheon in Budapest last week.
> >
> >
> https://cwiki.apache.org/confluence/display/OFBIZ/Apachecon+Workshop%3A+19th+November+2014
> > <
> https://cwiki.apache.org/confluence/display/OFBIZ/Apachecon+Workshop%3A+19th+November+2014
> >
> >
> > A key point to remember is that no decisions were made and that these are
> > just the notes from our discussions.
> >
> > As you will see, a lot of ideas/proposals came up that need community
> > feedback, discussion and opinion.
> >
> > Please feel free to provide any feedback or comments using this mailing
> list
> > thread.
> >
> > Thanks
> > Sharan
> >
> >
> >
> > --
> > View this message in context:
> http://ofbiz.135035.n4.nabble.com/Notes-from-Apachecon-EU-Budapest-Meeting-tp4658991.html
> > Sent from the OFBiz - User mailing list archive at Nabble.com.
> >
>

[Jacques Le Roux]

I guess this is what Todd means http://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture

Jacques

Le 26/11/2014 16:38, Pierre Smits a écrit :

> Todd, all,
>
> Don't you just love those acronyms.... What is meant by that (DITA)?
> Remember, the audience is diverse.
>
> DITA as opposed to PITA?
>
> Al jokes apart. Documentation is important with respect to adoption. From
> all angles: business, development, deployment/implementation, etc.
>
> Regards,
>
> Pierre Smits
>
> *ORRTIZ.COM <http://www.orrtiz.com>*
> Services & Solutions for Cloud-
> Based Manufacturing, Professional
> Services and Retail & Trade
> http://www.orrtiz.com
>
> On Wed, Nov 26, 2014 at 4:11 PM, Todd Thorner <[hidden email]>
> wrote:
>
>> Quick opinions on the rough ideas...
>>
>> 1. Turn the "kernel" into something based around containers (e.g.
>> docker).  This approach could also apply to many dev-ops considerations
>> that are internal to the project.
>> 2. Make DITA the basis of all documentation.
>>
>>
>>
>> On 14-11-26 04:13 AM, Sharan-F wrote:
>>> Hi Everyone
>>>
>>> Please see below for the link to the notes from the meeting we held at
>>> Apacheon in Budapest last week.
>>>
>>>
>> https://cwiki.apache.org/confluence/display/OFBIZ/Apachecon+Workshop%3A+19th+November+2014
>>> <
>> https://cwiki.apache.org/confluence/display/OFBIZ/Apachecon+Workshop%3A+19th+November+2014
>>>
>>> A key point to remember is that no decisions were made and that these are
>>> just the notes from our discussions.
>>>
>>> As you will see, a lot of ideas/proposals came up that need community
>>> feedback, discussion and opinion.
>>>
>>> Please feel free to provide any feedback or comments using this mailing
>> list
>>> thread.
>>>
>>> Thanks
>>> Sharan
>>>
>>>
>>>
>>> --
>>> View this message in context:
>> http://ofbiz.135035.n4.nabble.com/Notes-from-Apachecon-EU-Budapest-Meeting-tp4658991.html
>>> Sent from the OFBiz - User mailing list archive at Nabble.com.
>>>

[Todd Thorner]

DITA is an OASIS "standard" that has been steadily supplanting other
"standards" like Docbook to become a dev-ops go-to for information
architecture: http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.html

Having said that, it comes down to a business-versus-bureaucracy thing.
 One of the rough ideas bandied at Apachecon was to develop "a strategy
to encourage more business users," and typically that means minimizing
the bureaucracy of the project (as in: don't scare away business
managers who are assessing OFBiz on behalf of their organization).

DITA's advantage over things like wiki-only or HTML-only (or trying to
maintain wiki markup plus HTML markup plus whatever else) is its ability
to store content as single-sourced files and then transform those files
from their native XML format into appropriate end user formats (e.g.
XHTML or PDF/FOP or SCORM or even some wiki markups depending on the
plugged-in extension to the transformation engine).  For information on
the most popular transformation engine (which takes raw DITA files and
transforms them from their native XML format to a format that end users
can read), try this: http://www.dita-ot.org/1.8/.

Most OFBiz documentation contributors, understandably, have been
comfortable gaining professional experience using things like Docbook
(which is by no means obsolete but rather is suffering from the recent
migration toward DITA), so any embrace of DITA could necessitate some
kind of bureaucratic dictate that "all contributors will now write
documentation based on the DITA standard," which is not likely to go
over well with either the writer-contributors or the business managers
assessing OFBiz while hoping to avoid overly-bureaucratic open source
projects.

Probably the best approach, at least for the next few years, is to
encourage doc commits of DITA-based source files while continuing to
accept with thanks everything writers are willing to contribute.  Some
of the Open Toolkit engine transformations (which at the end of the day
are ant-target-thingies) might be used to backward-transform someone's
Docbook contribution into DITA format.  A goal worthy of debate on the
developer ml is to consider a day "three years from now" when:

- most tech writers are contributing DITA files
- transformations exist to turn other contributed docs into DITA files
- transformations exist to turn single-sourced DITA files into
appropriate end user documents (wiki pages, etc.)

The biggest advantage of single-sourcing documentation is that when
OFBiz framework specs change you need only edit one file to enable
necessary updates to information destined for multiple end user doc
targets, instead of wondering if there's another wiki page (or PDF or
whatever) out there somewhere that got overlooked.

Beyond this overview I'm too tech-tetched to help much with putting the
transformation engine through a set of tests or anything like that.
Those who know Ant should have few problems experimenting here & there
(resources permitting of course).

I will add some final links to peruse:

The Derby project appears to use DITA as the basis of its documentation:
https://db.apache.org/derby/manuals/index.html

The FOP project appears to be debating whether or not to tighten up the
integration/coupling of DITA and FOP:
https://mail-archives.apache.org/mod_mbox/xmlgraphics-fop-dev/201403.mbox/%3C533322F6.8050907@...%3E

The OpenOffice project appears to have been considering DITA as a format
for its documentation-related source files (although Confluence markup
as an engine output target doesn't appear to be implemented inside
Apache or elsewhere):
https://cwiki.apache.org/confluence/display/OOOUSERS/User+Documentation+Plan




On 14-11-26 07:38 AM, Pierre Smits wrote:

> Todd, all,
>
> Don't you just love those acronyms.... What is meant by that (DITA)?
> Remember, the audience is diverse.
>
> DITA as opposed to PITA?
>
> Al jokes apart. Documentation is important with respect to adoption. From
> all angles: business, development, deployment/implementation, etc.
>
> Regards,
>
> Pierre Smits
>
> *ORRTIZ.COM <http://www.orrtiz.com>*
> Services & Solutions for Cloud-
> Based Manufacturing, Professional
> Services and Retail & Trade
> http://www.orrtiz.com
>
> On Wed, Nov 26, 2014 at 4:11 PM, Todd Thorner <[hidden email]>
> wrote:
>
>> Quick opinions on the rough ideas...
>>
>> 1. Turn the "kernel" into something based around containers (e.g.
>> docker).  This approach could also apply to many dev-ops considerations
>> that are internal to the project.
>> 2. Make DITA the basis of all documentation.
>>
>>
>>
>> On 14-11-26 04:13 AM, Sharan-F wrote:
>>> Hi Everyone
>>>
>>> Please see below for the link to the notes from the meeting we held at
>>> Apacheon in Budapest last week.
>>>
>>>
>> https://cwiki.apache.org/confluence/display/OFBIZ/Apachecon+Workshop%3A+19th+November+2014
>>> <
>> https://cwiki.apache.org/confluence/display/OFBIZ/Apachecon+Workshop%3A+19th+November+2014
>>>
>>>
>>> A key point to remember is that no decisions were made and that these are
>>> just the notes from our discussions.
>>>
>>> As you will see, a lot of ideas/proposals came up that need community
>>> feedback, discussion and opinion.
>>>
>>> Please feel free to provide any feedback or comments using this mailing
>> list
>>> thread.
>>>
>>> Thanks
>>> Sharan
>>>
>>>
>>>
>>> --
>>> View this message in context:
>> http://ofbiz.135035.n4.nabble.com/Notes-from-Apachecon-EU-Budapest-Meeting-tp4658991.html
>>> Sent from the OFBiz - User mailing list archive at Nabble.com.
>>>
>>
>

[Ron Wheeler]

2 good ideas.

Ron
On 26/11/2014 10:11 AM, Todd Thorner wrote:

> Quick opinions on the rough ideas...
>
> 1. Turn the "kernel" into something based around containers (e.g.
> docker).  This approach could also apply to many dev-ops considerations
> that are internal to the project.
> 2. Make DITA the basis of all documentation.
>
>
>
> On 14-11-26 04:13 AM, Sharan-F wrote:
>> Hi Everyone
>>
>> Please see below for the link to the notes from the meeting we held at
>> Apacheon in Budapest last week.
>>
>> https://cwiki.apache.org/confluence/display/OFBIZ/Apachecon+Workshop%3A+19th+November+2014
>> <https://cwiki.apache.org/confluence/display/OFBIZ/Apachecon+Workshop%3A+19th+November+2014>
>>
>> A key point to remember is that no decisions were made and that these are
>> just the notes from our discussions.
>>
>> As you will see, a lot of ideas/proposals came up that need community
>> feedback, discussion and opinion.
>>
>> Please feel free to provide any feedback or comments using this mailing list
>> thread.
>>
>> Thanks
>> Sharan
>>
>>
>>
>> --
>> View this message in context: http://ofbiz.135035.n4.nabble.com/Notes-from-Apachecon-EU-Budapest-Meeting-tp4658991.html
>> Sent from the OFBiz - User mailing list archive at Nabble.com.
>>

--
Ron Wheeler
President
Artifact Software Inc
email: [hidden email]
skype: ronaldmwheeler
phone: [phone], ext 102

[Shi Jinghai-3]

+1 to docker, including OFBiz+MySQL, OFBiz+PostgreSQL.


在 2014-11-26，下午11:11，Todd Thorner <[hidden email]> 写道：

> Quick opinions on the rough ideas...
>
> 1. Turn the "kernel" into something based around containers (e.g.
> docker).  This approach could also apply to many dev-ops considerations
> that are internal to the project.
> 2. Make DITA the basis of all documentation.
>
>
>
> On 14-11-26 04:13 AM, Sharan-F wrote:
>> Hi Everyone
>>
>> Please see below for the link to the notes from the meeting we held at
>> Apacheon in Budapest last week.
>>
>> https://cwiki.apache.org/confluence/display/OFBIZ/Apachecon+Workshop%3A+19th+November+2014
>> <https://cwiki.apache.org/confluence/display/OFBIZ/Apachecon+Workshop%3A+19th+November+2014>  
>>
>> A key point to remember is that no decisions were made and that these are
>> just the notes from our discussions.
>>
>> As you will see, a lot of ideas/proposals came up that need community
>> feedback, discussion and opinion.
>>
>> Please feel free to provide any feedback or comments using this mailing list
>> thread.
>>
>> Thanks
>> Sharan
>>
>>
>>
>> --
>> View this message in context: http://ofbiz.135035.n4.nabble.com/Notes-from-Apachecon-EU-Budapest-Meeting-tp4658991.html
>> Sent from the OFBiz - User mailing list archive at Nabble.com.
>>
>

[Sharan-F]

Hi Todd

Thanks for explaining this and giving the links.

I'd like to investigate this as I'm keen to understand if we need to discuss changing our approach to in application documentation.

Thanks
Sharan

[Mike Z]

I think that recently the docs have made a great leap forward thanks to the
good folks here on the mailing list.  The more comfortable people are with
the wiki the more it will be used.  Confluence is a standard wiki used
throughout the industry and I think it would be a mistake to change things
just as it is gaining steam.

Sent from my BlackBerry® PlayBook™
www.blackberry.com

------------------------------
*From:* "Sharan-F" <[hidden email]>
*To:* "[hidden email]" <[hidden email]>
*Sent:* November 28, 2014 6:02 AM
*Subject:* Re: Notes from Apachecon EU Budapest Meeting

Hi Todd

Thanks for explaining this and giving the links.

I'd like to investigate this as I'm keen to understand if we need to discuss
changing our approach to in application documentation.

Thanks
Sharan



--
View this message in context:
http://ofbiz.135035.n4.nabble.com/Notes-from-Apachecon-EU-Budapest-Meeting-tp4658991p4659098.html
Sent from the OFBiz - User mailing list archive at Nabble.com.

[Todd Thorner]

"...used throughout the industry" is known as argumentum ad populum --
and besides it isn't even a very accurate assertion.  Perhaps Mr. Z is
referring to the use of Confluence within the ASF, and "available
support" is of course a decent argument for sticking with wiki-only
documentation as long as the ASF provides superlative infrastructure &
support.  Otherwise it <i>will</i> become a sticky wiki wicket that
offers only greater long-term restrictions than something like
single-sourced DITA or Docbook (even with adequate wiki support the
writing as it were appears to be on the proverbial wall regarding
technical communication trends).

There is such a thing as change management.  Indeed, if there were no
such thing, bureaucracy would grind all potential change to a permanent
halt.  Change for change's sake is a business management pitfall,
obviously, so it comes down to a decision about whether the project has
enough resources to spare for investigating DITA (which is gaining
popularity among tech writers more than any similar typing architecture
or proprietary wiki engine).

"Change because there's something new to try" is a management no-no.

"Don't change because everyone is used to the old way" is a management
no-no.

I am ignorant about this project's current resources or ultimate
aspirations.  I'm guessing that open source human resources are scarce,
which typically means (at least in the software game) that documentation
gets tartarooed toward "oh, anyone can whip up some documentation during
the final days before release" oblivion.  Fair enough, and contributors
are being generous with improvements to the documentation as it exists
right now, so if resources are less than available for appropriate
change management commitment then the existing wiki is the way to go for
the next few years.  As a tech writer, though, one with experience
stretching back to the 80s, I am confident asserting that after "the
next few years" a proprietary wiki engine, when compared with
single-sourced XML markup that can target multiple output formats, will
come to be seen as more of an anchor than a lifeline.  Perhaps a few
years out is a reasonable dart-toss goal for a documentation change
management sub-project.

Aside: my "two cents" OFBiz wish list has CMIS integration at the top
(minor sub-project with a large potential end user payoff), as well as
something like <a href="https://coreos.com/" target="_blank">CoreOS</a>
integration right beneath that (major sub-project with a ginormous
potential end user & dev-ops payoff).  I try, of course, to be one of
those "take what I can and be thankful" users because my typical open
source contributions amount to cybergum-flapping opinions.



On 14-11-28 06:51 PM, Mike Z wrote:

> I think that recently the docs have made a great leap forward thanks to the
> good folks here on the mailing list.  The more comfortable people are with
> the wiki the more it will be used.  Confluence is a standard wiki used
> throughout the industry and I think it would be a mistake to change things
> just as it is gaining steam.
>
> Sent from my BlackBerry® PlayBook™
> www.blackberry.com
>
> ------------------------------
> *From:* "Sharan-F" <[hidden email]>
> *To:* "[hidden email]" <[hidden email]>
> *Sent:* November 28, 2014 6:02 AM
> *Subject:* Re: Notes from Apachecon EU Budapest Meeting
>
> Hi Todd
>
> Thanks for explaining this and giving the links.
>
> I'd like to investigate this as I'm keen to understand if we need to discuss
> changing our approach to in application documentation.
>
> Thanks
> Sharan
>
>
>
> --
> View this message in context:
> http://ofbiz.135035.n4.nabble.com/Notes-from-Apachecon-EU-Budapest-Meeting-tp4658991p4659098.html
> Sent from the OFBiz - User mailing list archive at Nabble.com.
>