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.
>>>
>
>
