[DISCUSSION] OFBiz End User Wiki Documentation

[Sharan-F]

Hi Everyone

i'd like to put forward another proposal for discussion around the project End User Documentation.

We know that we have incomplete documentation and need an active strategy to complete it. The help itself can be divided it into two distinct areas

1. Online / in Application Help (NOTE: A discussion for this has been started in another thread)
2. User Documentation on the Wiki


User Documentation on the Wiki
Our current End User Documentation is fragmented (End User Docs, Requirements and Designs, Wiki) and mixed in with various other documentation on the Wiki. Attempts have been made to create the documentation but the level of information required has been varied and unclear.

Confluence is the Apache tool for managing wiki but it does have its limits that have caused frustration in the past.

Proposal
Our community surveys show that we don't have a lot of typical 'End Users' in our Community Base. The users that we do have are more 'Key Users' or 'Application Experts'. What I mean here is that they are users that understand their own business flows and are interested in knowing how to setup OFBiz for their business.

Rather than be focussed on End Users – I think this documentation could be focussed on the 'Key Users' and giving them the information they need to configure or setup OFBiz for a business. As a possible guide it  could contain the following:

- business process flows
- use cases
- application guide (details and steps for implementing the process flow)
- configuration instructions
- tips and tricks
- glossary
- details about data loading (e.g seed or production data)

Key Benefit
Our user documentation has a clear purpose rather than trying to fulfill mulitple different roles

Once again these are my initial thoughts so am very happy (and keen) to get feedback from the community (especially user) about this.

Thanks
Sharan

[Todd Thorner]

The key to minimizing effort is single-sourcing.  That is the business
requirement (maybe), now the community must settle on appropriate
technologies.

My opinion is that DocBook is obsolete.  One non-committer vote for DITA.



On 15-05-21 09:59 AM, Sharan-F wrote:

> Hi Everyone
>
> i'd like to put forward another proposal for discussion around the project
> End User Documentation.
>
> We know that we have incomplete documentation and need an active strategy to
> complete it. The help itself can be divided it into two distinct areas
>
> 1. Online / in Application Help *(NOTE*: A discussion for this has been
> started in another thread)
> 2. User Documentation on the Wiki
>
> *
> User Documentation on the Wiki *
> Our current End User Documentation is fragmented (End User Docs,
> Requirements and Designs, Wiki) and mixed in with various other
> documentation on the Wiki. Attempts have been made to create the
> documentation but the level of information required has been varied and
> unclear.
>
> Confluence is the Apache tool for managing wiki but it does have its limits
> that have caused frustration in the past.
>
> *Proposal*
> Our community surveys show that we don't have a lot of typical 'End Users'
> in our Community Base. The users that we do have are more 'Key Users' or
> 'Application Experts'. What I mean here is that they are users that
> understand their own business flows and are interested in knowing how to
> setup OFBiz for their business.
>
> Rather than be focussed on End Users – I think this documentation could be
> focussed on the 'Key Users' and giving them the information they need to
> configure or setup OFBiz for a business. As a possible guide it  could
> contain the following:
>
> - business process flows
> - use cases
> - application guide (details and steps for implementing the process flow)
> - configuration instructions
> - tips and tricks
> - glossary
> - details about data loading (e.g seed or production data)
>
> *Key Benefit*
> Our user documentation has a clear purpose rather than trying to fulfill
> mulitple different roles
>
> Once again these are my initial thoughts so am very happy (and keen) to get
> feedback from the community (especially user) about this.
>
> Thanks
> Sharan
>
>
>
> --
> View this message in context: http://ofbiz.135035.n4.nabble.com/DISCUSSION-OFBiz-End-User-Wiki-Documentation-tp4668872.html
> Sent from the OFBiz - User mailing list archive at Nabble.com.
>

[Ron Wheeler]

http://blogs.atlassian.com/2010/11/technical_writing_wiki_single_source_publishing/
Great summary of how to use Confluence in an environment that includes a
number of source formats and desired output.

I use DITA for software docs and like the way that it integrates with
Eclipse/STS.

Ron


On 21/05/2015 1:22 PM, Todd Thorner wrote:

> The key to minimizing effort is single-sourcing.  That is the business
> requirement (maybe), now the community must settle on appropriate
> technologies.
>
> My opinion is that DocBook is obsolete.  One non-committer vote for DITA.
>
>
>
> On 15-05-21 09:59 AM, Sharan-F wrote:
>> Hi Everyone
>>
>> i'd like to put forward another proposal for discussion around the project
>> End User Documentation.
>>
>> We know that we have incomplete documentation and need an active strategy to
>> complete it. The help itself can be divided it into two distinct areas
>>
>> 1. Online / in Application Help *(NOTE*: A discussion for this has been
>> started in another thread)
>> 2. User Documentation on the Wiki
>>
>> *
>> User Documentation on the Wiki *
>> Our current End User Documentation is fragmented (End User Docs,
>> Requirements and Designs, Wiki) and mixed in with various other
>> documentation on the Wiki. Attempts have been made to create the
>> documentation but the level of information required has been varied and
>> unclear.
>>
>> Confluence is the Apache tool for managing wiki but it does have its limits
>> that have caused frustration in the past.
>>
>> *Proposal*
>> Our community surveys show that we don't have a lot of typical 'End Users'
>> in our Community Base. The users that we do have are more 'Key Users' or
>> 'Application Experts'. What I mean here is that they are users that
>> understand their own business flows and are interested in knowing how to
>> setup OFBiz for their business.
>>
>> Rather than be focussed on End Users – I think this documentation could be
>> focussed on the 'Key Users' and giving them the information they need to
>> configure or setup OFBiz for a business. As a possible guide it  could
>> contain the following:
>>
>> - business process flows
>> - use cases
>> - application guide (details and steps for implementing the process flow)
>> - configuration instructions
>> - tips and tricks
>> - glossary
>> - details about data loading (e.g seed or production data)
>>
>> *Key Benefit*
>> Our user documentation has a clear purpose rather than trying to fulfill
>> mulitple different roles
>>
>> Once again these are my initial thoughts so am very happy (and keen) to get
>> feedback from the community (especially user) about this.
>>
>> Thanks
>> Sharan
>>
>>
>>
>> --
>> View this message in context: http://ofbiz.135035.n4.nabble.com/DISCUSSION-OFBiz-End-User-Wiki-Documentation-tp4668872.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

[Todd Thorner]

That's some great information, thanks, and thanks in general to all the
documentation contributors who continue improving what's available for
end users.  Confluence seems to be a must-have for the OFBiz project,
although it's unwise for a business or open source project to insist
that any specific technology become <i>the</i> starting point of ECM
considerations.  Indeed, something like DITA also falls into the "let's
think about technologies later" category (I pulled a bit of an
eager-gomer move with my "vote for DITA" at such a preliminary
stage--although I do prefer it to other documentation-related
architectures).

Setting aside out-of-scope things like possible roadmaps for the OFBiz
codebase itself to implement interfaces to ECM systems
(design/development strategy), the project's documentation (including
end-user help, release notes, emails, etc.) comprises possible elements
of a separate & distinct ECM rollout.  There is a reason why I put
"maybe" into parentheses in my last message: getting "I'll be the
product owner" buy-in from at least one C-level manager (or the
equivalent for an open source project) is a showstopper-type requirement
... which is to say that few ECM rollouts succeed without a
business-imperative perspective driving everything forward.

Having said that, OFBiz's business requirements might include scope
reduction for things like emails, and might even reduce scope down to
"Just keep improving the documentation wherever it is."  Such specifics
are for the project's committers to determine.  Any
internal-to-the-project ECM rollout would need first and foremost to
wait on that kind of determination ... but those of us with backgrounds
in ECM & tech writing could help them with their eventual discussions by
explaining some of the preliminary topics up for consideration (again
the technologies themselves are best saved for "a few weeks down the road").

Since planning is paramount while a potential ECM product owner is yet
to be non-fictional, gaining traction might present a challenge.  Some
OFBiz committers might insist that something like Confluence or JIRA
needs be an enabler of any internal ECM strategy, and it might be the
case that ECM considerations beyond the content itself are out of scope
for the project ("It would be nice to have full-fledged ECM facilities
but the resources just aren't available").  In addition, if the OFBiz
project appears to already have technology lock-in here or there (e.g.
set-in-stone ASF bureaucracy-requirements for member projects), that too
is an important ECM planning consideration.

Yes, I can hear it: "Scr*w all that, Todd, where to start?"  Seeing as I
don't want to pretend that I'm going to be the product owner for any
potential ECM sub-project (such an owner must have superior knowledge of
OFBiz and its various development workflows), I am hesitant to make any
strong-headed suggestions.  That kind of cold feet, however represents
another common project pitfall, so I'll ask for others within e-earshot
to shout out a few more suggestions (on top of Mr. Wheeler's previous
message) and offer constructive criticism for what I'm about to suggest
myself ...

Those committers who take part in discussions about project strategy
(maybe it's all of them) are hereby *cough* commanded *cough* to:

<ol>
<li>Find a willing product owner for an internal ECM rollout.</li>
<li>Advise the community about available IT resources (e.g. bare-metal
vs. Cloud vs. "nothing").</li>
<li>Advise the community about any "it won't happen without this"
locked-in technologies that might impact ECM planning (including IDE
configurations, XML editors/parsers, ticket management systems, wiki
engines, etc.).</li>
</ol>

Here's hoping those HTML tags work inside this message.  In any case,
the next likely baby steps after that would involve composing an
inventory of broad-scope file types as well as sussing the potential for
content reuse (i.e. using a single source for publishing
context-sensitive help & wiki content & other output).  Meanwhile, I'll
go back to that great article about Confluence & single-sourcing to see
if I can't grab more than a cursory clue about round-tripping things.

Oh ... what the h-e-double-hockey-sticks, I'll break the "no early
technologies-talk" best practice again by getting these sourceforge
project links archived under the OFBiz category at MarkMail:
http://sourceforge.net/projects/dita2wiki/ and
http://sourceforge.net/projects/dita4publishers/ (mind you it's still
the case the DITA might represent for this project's documentation mere
architectural overkill:
http://idratherbewriting.com/2014/09/30/why-developers-will-never-adopt-dita/).



On 15-05-21 01:42 PM, Ron Wheeler wrote:

> http://blogs.atlassian.com/2010/11/technical_writing_wiki_single_source_publishing/
>
> Great summary of how to use Confluence in an environment that includes a
> number of source formats and desired output.
>
> I use DITA for software docs and like the way that it integrates with
> Eclipse/STS.
>
> Ron
>
>
> On 21/05/2015 1:22 PM, Todd Thorner wrote:
>> The key to minimizing effort is single-sourcing.  That is the business
>> requirement (maybe), now the community must settle on appropriate
>> technologies.
>>
>> My opinion is that DocBook is obsolete.  One non-committer vote for DITA.
>>
>>
>>
>> On 15-05-21 09:59 AM, Sharan-F wrote:
>>> Hi Everyone
>>>
>>> i'd like to put forward another proposal for discussion around the
>>> project
>>> End User Documentation.
>>>
>>> We know that we have incomplete documentation and need an active
>>> strategy to
>>> complete it. The help itself can be divided it into two distinct areas
>>>
>>> 1. Online / in Application Help *(NOTE*: A discussion for this has been
>>> started in another thread)
>>> 2. User Documentation on the Wiki
>>>
>>> *
>>> User Documentation on the Wiki *
>>> Our current End User Documentation is fragmented (End User Docs,
>>> Requirements and Designs, Wiki) and mixed in with various other
>>> documentation on the Wiki. Attempts have been made to create the
>>> documentation but the level of information required has been varied and
>>> unclear.
>>>
>>> Confluence is the Apache tool for managing wiki but it does have its
>>> limits
>>> that have caused frustration in the past.
>>>
>>> *Proposal*
>>> Our community surveys show that we don't have a lot of typical 'End
>>> Users'
>>> in our Community Base. The users that we do have are more 'Key Users' or
>>> 'Application Experts'. What I mean here is that they are users that
>>> understand their own business flows and are interested in knowing how to
>>> setup OFBiz for their business.
>>>
>>> Rather than be focussed on End Users – I think this documentation
>>> could be
>>> focussed on the 'Key Users' and giving them the information they need to
>>> configure or setup OFBiz for a business. As a possible guide it  could
>>> contain the following:
>>>
>>> - business process flows
>>> - use cases
>>> - application guide (details and steps for implementing the process
>>> flow)
>>> - configuration instructions
>>> - tips and tricks
>>> - glossary
>>> - details about data loading (e.g seed or production data)
>>>
>>> *Key Benefit*
>>> Our user documentation has a clear purpose rather than trying to fulfill
>>> mulitple different roles
>>>
>>> Once again these are my initial thoughts so am very happy (and keen)
>>> to get
>>> feedback from the community (especially user) about this.
>>>
>>> Thanks
>>> Sharan
>>>
>>>
>>>
>>> --
>>> View this message in context:
>>> http://ofbiz.135035.n4.nabble.com/DISCUSSION-OFBiz-End-User-Wiki-Documentation-tp4668872.html
>>>
>>> Sent from the OFBiz - User mailing list archive at Nabble.com.
>>>
>
>

[Sharan-F]

Hi Ron and Todd

Thank you both for the feedback and I've taken a look at the links you mentioned. (I think this could be useful in the other discussion thread I created around the online application help and the idea of extracting it from OFBiz so that it could be maintained, updated and then re-introduced or packaged separately as another project deliverable or an addon. Ron - I have a feeling of what you're going to say here....:-)

When I created this discussion thread my main focus was on getting some agreement on the help content and we are beginning to talk about available technologies to manage it, store it and make it accessible. I agree that these are all valid points and linked to creating a the complete strategy.

A while ago I started putting this together

https://cwiki.apache.org/confluence/display/OFBIZ/Draft+Documentation+Roadmaphttp://

so it is something that can be developed as we progress and get more information.

I'd really like to get some movement on improving the OFBiz end user documentation. I started with a re-organisation and consolidation of the Technical Documentation which is complete, so now we have the content updated, we can decide what to do with and how to manage it (i.e tools, format etc).

The End User documentation isn't at that stage yet so I wanted to get at least some agreement about the minimum it could contain so that we could start building a structure around the content.

I'd like to use a similar approach that I used for the consolidation of the Technical Documentation and in this case we will be merging data from at least 2 other workspaces plus the wiki into (hopefully) a single coherent user guide.
 
At a high level this is where I'd like to go using what we have in place now (i.e. Confluence)

1) Let's agree some minimum content and structure for the end user wiki documentation
2) We review what we already have that fits into those categories and structure
3) We identify any areas where documentation is missing
4) We create documentation for the missing areas
5) Once we have a complete guide then we can decide on what technology we use to manage it going forward.

I know it's only small steps (though some of these tasks may be significant) but I hope it will take us in the right direction so that at least we have something useful that our users want.

Thanks
Sharan

[Ron Wheeler]

We should solicit input from the OFBiz SI community.
I would think that they would want end-user documentation in a form that
they can easily brand and customize.

This makes me think that DITA would be a good source target since it
would allow SIs to produce customized and branded documentation in
different formats including on-line help and manuals in PDF.
They could override or enhance individual topics as required.
They could change fonts, layouts, logos and colors to suite their
corporate image or brand it in the customer's scheme without having to
touch the content.

Translation is easier in DITA.

Ron

On 24/05/2015 7:41 AM, Sharan-F wrote:

> Hi Ron and Todd
>
> Thank you both for the feedback and I've taken a look at the links you
> mentioned. (I think this could be useful in the other discussion thread I
> created around the online application help and the idea of extracting it
> from OFBiz so that it could be maintained, updated and then re-introduced or
> packaged separately as another project deliverable or an addon. Ron - I have
> a feeling of what you're going to say here....:-)
>
> When I created this discussion thread my main focus was on getting some
> agreement on the help content and we are beginning to talk about available
> technologies to manage it, store it and make it accessible. I agree that
> these are all valid points and linked to creating a the complete strategy.
>
> A while ago I started putting this together
>
> https://cwiki.apache.org/confluence/display/OFBIZ/Draft+Documentation+Roadmaphttp://
> <https://cwiki.apache.org/confluence/display/OFBIZ/Draft+Documentation+Roadmaphttp://>
>
> so it is something that can be developed as we progress and get more
> information.
>
> I'd really like to get some movement on improving the OFBiz end user
> documentation. I started with a re-organisation and consolidation of the
> Technical Documentation which is complete, so now we have the content
> updated, we can decide what to do with and how to manage it (i.e tools,
> format etc).
>
> The End User documentation isn't at that stage yet so I wanted to get at
> least some agreement about the minimum it could contain so that we could
> start building a structure around the content.
>
> I'd like to use a similar approach that I used for the consolidation of the
> Technical Documentation and in this case we will be merging data from at
> least 2 other workspaces plus the wiki into (hopefully) a single coherent
> user guide.
>  
> At a high level this is where I'd like to go using what we have in place now
> (i.e. Confluence)
>
> 1) Let's agree some minimum content and structure for the end user wiki
> documentation
> 2) We review what we already have that fits into those categories and
> structure
> 3) We identify any areas where documentation is missing
> 4) We create documentation for the missing areas
> 5) Once we have a complete guide then we can decide on what technology we
> use to manage it going forward.
>
> I know it's only small steps (though some of these tasks may be significant)
> but I hope it will take us in the right direction so that at least we have
> something useful that our users want.
>
> Thanks
> Sharan
>
>
>
> --
> View this message in context: http://ofbiz.135035.n4.nabble.com/DISCUSSION-OFBiz-End-User-Wiki-Documentation-tp4668872p4668952.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

[Sharan-F]

Hi Ron

What do you mean by SI? You're using an abbreviation I don't know.

Thanks
Sharan

[Ron Wheeler]

System Integrator.
Every one else except you and I and a couple of other end-users???

Ron

On 24/05/2015 11:04 AM, Sharan-F wrote:

> Hi Ron
>
> What do you mean by SI? You're using an abbreviation I don't know.
>
> Thanks
> Sharan
>
>
>
> --
> View this message in context: http://ofbiz.135035.n4.nabble.com/DISCUSSION-OFBiz-End-User-Wiki-Documentation-tp4668872p4668956.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