You are viewing a plain text version of this content. The canonical link for it is here.
Posted to user@ofbiz.apache.org by Sharan Foga <sh...@gmail.com> on 2017/11/15 14:29:56 UTC
Some Information for Creating Modular Documentation
Hi All
(I'm resending this message as the original message I sent this morning
didn't get through to the mailing list. I seem to have an intermittent
problem with posting somehow ;-)
I recently interviewed Robert Kratky, a Technical Writer from Red Hat
about his presentation on documentation at the Open Source Summit in
Prague a few weeks ago. He has some good advice for us and anyone
looking at writing good documentation. His talk was about how to move
from feature based documentation (which is what we have tended to do) to
more user story based documentation that is driven more by how our users
use the software.
You can listen to the interview at the link below:
https://wp.me/p8gHED-QF
Please take a look at his presentation
schd.ws/hosted_files/osseu17/5f/%28OSSEU%2017%29%20Going%20Modular-%20Turning%20Legacy%20Docs%20into%20User-Story-Based%20Content.pdf
and also at the github repo with some guidelines for writing modular
documentation,
https://github.com/redhat-documentation/modular-docs
So as our community continues in its documentation efforts I'd like to
highlight that anyone can contribute and help by letting us know how you
are using OFBiz and what are your main user stories.
Thanks
Sharan
Re: Some Information for Creating Modular Documentation
Posted by Taher Alkhateeb <sl...@gmail.com>.
Great advice and resources thank you for sharing. I will take into
consideration some of this while implementing the PoC
On Nov 15, 2017 7:53 PM, "Jacques Le Roux" <ja...@les7arts.com>
wrote:
> Thanks Sharan,
>
> This is more for users I guess? Could the technical documentation be based
> on the same?
>
> So we would need 1st to collect and, I guess more surely, to create the
> user stories on which to base our user documentation on, right?
>
> I know we have some already, thinks like that, right?
> https://cwiki.apache.org/confluence/display/OFBIZ/PIM+User+
> Stories,+Use+Cases,+and+Test+Cases
> https://cwiki.apache.org/confluence/display/OFBIZ/Sales+
> Order+Management+User+Stories,+Use+Cases,+and+Test+Cases
> Todos:
> https://cwiki.apache.org/confluence/display/OFBIZ/Order+
> Fulfillment+Process+User+Stories,+Use+Cases+and+Test+Cases
> https://cwiki.apache.org/confluence/display/OFBIZ/Customer+
> Relationship+Management+(CRM)+User+Stories,+Use+Cases,+and+Test+Cases
>
> That's certainly the best long range way, but it will take some ;)
>
> Jacques
>
>
> Le 15/11/2017 à 16:11, Todd Thorner a écrit :
>
>> Yes, that is best practice for documentation, thanks for sharing the
>> links.
>>
>>
>>
>> On 17-11-15 06:29 AM, Sharan Foga wrote:
>>
>>> Hi All
>>>
>>> (I'm resending this message as the original message I sent this morning
>>> didn't get through to the mailing list. I seem to have an intermittent
>>> problem with posting somehow ;-)
>>>
>>> I recently interviewed Robert Kratky, a Technical Writer from Red Hat
>>> about his presentation on documentation at the Open Source Summit in Prague
>>> a few weeks ago. He has some good advice for us and anyone looking at
>>> writing good documentation. His talk was about how to move from feature
>>> based documentation (which is what we have tended to do) to more user story
>>> based documentation that is driven more by how our users use the software.
>>>
>>> You can listen to the interview at the link below:
>>>
>>> https://wp.me/p8gHED-QF
>>>
>>> Please take a look at his presentation
>>>
>>> schd.ws/hosted_files/osseu17/5f/%28OSSEU%2017%29%20Going%20M
>>> odular-%20Turning%20Legacy%20Docs%20into%20User-Story-Based%
>>> 20Content.pdf
>>>
>>> and also at the github repo with some guidelines for writing modular
>>> documentation,
>>>
>>> https://github.com/redhat-documentation/modular-docs
>>>
>>> So as our community continues in its documentation efforts I'd like to
>>> highlight that anyone can contribute and help by letting us know how you
>>> are using OFBiz and what are your main user stories.
>>>
>>> Thanks
>>> Sharan
>>>
>>>
>>>
>>>
>>
>>
>
Re: Some Information for Creating Modular Documentation
Posted by Taher Alkhateeb <sl...@gmail.com>.
Hi Todd, thank you for sharing your thoughts :)
So perhaps you might have been focused the word "liability". Maybe
looking at the context of the whole email might make it a bit more
clear (sorry if I'm not). I'm a strong advocate for writing good
documentation and I took several initiatives due to its importance [1]
[2] [3].
Anyway, I think perhaps the purpose of this thread is to discuss the
documentation strategy more than our opinion of what documentation
means to us. I think we can all safely agree that documentation is
important.
[1] https://s.apache.org/ISpM
[2] https://issues.apache.org/jira/browse/OFBIZ-9873
[3] subversion r1751309, r1786562, r1805947
On Fri, Nov 17, 2017 at 7:26 PM, Todd Thorner <tt...@infotinuum.com> wrote:
> Documentation is never a liability, unless one considers consumers to be a
> liability (which would make one more of a do-as-you-are-told bureaucrat than
> an I-hope-to-please-you business manager).
>
>
> Consumers, far from being a liability, are the most important considerations
> within any healthy economy. As Frederic Bastiat said (translated from the
> original French): "Treat all economic questions from the viewpoint of the
> consumer, for the interests of the consumer are the interests of the human
> race."
>
>
> Fortunately, each of us spends the vast majority of life, even while at work
> producing things for market, consuming things already available from various
> markets. Each must embrace the concept of consumer as king/queen, or else
> risk undermining everyone's economic viability (i.e. a slippery slope toward
> the absolute bureaucracy of socialist totalitarianism whether it happens to
> resemble Soviet-style bureaucracy or zwangswirtschaft-style bureaucracy).
>
>
> Bottom line: this is a user mailing list, which makes it a mailing list
> catered toward OFBiz consumers. When consumers encounter implications that
> they are not the most important consideration, they become inspired to take
> their business elsewhere (at least until encroaching totalitarianism
> precludes such options as things become more bureaucratic).
>
>
>
>
> On 17-11-17 01:34 AM, Taher Alkhateeb wrote:
>
>> I went through the material (thank you again for sharing) and I have a
>> few additional thoughts to share.
>>
>> Primarily I think there is no silver bullet, and there is no solution
>> that somehow makes documentation "Fun". It's always going to be a
>> liability that just comes with any software solution. With that being
>> said, I would argue that a guide-based vs feature-based documentation
>> is not necessarily mutually exclusive. You can have both and they
>> complement each other.
>>
>> So maybe we should consider designing documentation such that:
>> - Guides are good, we need a few good ones for common scenarios (hello
>> world, new component. deployment, security, caching, etc ...)
>> - Reference material is also good, possibly broken down by feature /
>> module.
>> - Everything should ideally be as short and concise as reasonably
>> possible,
>> - Content reuse should be applied as much as possible.
>> - Documentation needs to constantly evolve (add, change and especially
>> _REMOVE_)
>>
>> A good example for documentation I always like to use is Gradle [1].
>> They really have fantastic documentation and I use ALL OF IT. I used
>> the guides many times, but I also constantly look at the DSL
>> reference. And when I am trying to implement an advanced feature, I
>> roll my sleeves and start digging into the API documentation.
>>
>> To summarize, I think perhaps we should consider the following types
>> of documentation as beneficial:
>> - Focused guides (to achieve a specific task)
>> - Reference documentation (not necessarily covering 100% of everything)
>> - API documentation (auto generated from source code)
>>
>> [1] https://gradle.org/docs/
>>
>> On Thu, Nov 16, 2017 at 9:05 AM, Jacques Le Roux
>> <ja...@les7arts.com> wrote:
>>>
>>> Le 16/11/2017 à 06:34, Woosang Jung a écrit :
>>>>
>>>> On 2017-11-15 10:10, Jacques Le Roux <ja...@les7arts.com>
>>>> wrote:
>>>>>
>>>>> Le 15/11/2017 à 17:54, Jacques Le Roux a écrit :
>>>>>>
>>>>>> This is more for users I guess? Could the technical documentation be
>>>>>> based on the same?
>>>>>
>>>>> I read a bit more and now clearly understand that it's applicable to
>>>>> all
>>>>> (user, technical, etc.)
>>>>>
>>>>> Jacques
>>>>
>>>> I'm all for it. How do I let you know what my main user stories are? Do
>>>> I
>>>> add to this thread?
>>>>
>>>> Woosang
>>>
>>> Hi Woosang,
>>>
>>> Here are several possible ways for providing your user stories, by order
>>> of
>>> preference:
>>>
>>> 1. If you are a registered wiki contributor (recommended) and want to
>>> format
>>> them in Confluence (easier for us), look at the wiki pages I referred
>>> above and see if a new page is needed. If you need, create a new page
>>> and
>>> add you user stories there else use an existing page
>>> 2. If you are not a registered wiki contributor and don't want to be one,
>>> you can still add your Confluence formatted user stories as comments in
>>> existing pages. So if you need a new page you need to ask for its
>>> creation before adding comments...
>>> 3. If you don't want to provide Confluence formatted user stories then
>>> open
>>> a Jira and add your unformatted user stories in a text file
>>>
>>>
>>> https://cwiki.apache.org/confluence/display/OFBIZ/OFBiz+Contributors+Best+Practices
>>>
>>> Thanks
>>>
>>> Jacques
>>> PS:we will maybe need to update
>>>
>>> https://cwiki.apache.org/confluence/display/OFBIZ/OFBiz+Contributors+Best+Practices
>>> for how to document using information above and more...
>>>
>
Re: Some Information for Creating Modular Documentation
Posted by Todd Thorner <tt...@infotinuum.com>.
Documentation is never a liability, unless one considers consumers to be
a liability (which would make one more of a do-as-you-are-told
bureaucrat than an I-hope-to-please-you business manager).
Consumers, far from being a liability, are the most important
considerations within any healthy economy. As Frederic Bastiat said
(translated from the original French): "Treat all economic questions
from the viewpoint of the consumer, for the interests of the consumer
are the interests of the human race."
Fortunately, each of us spends the vast majority of life, even while at
work producing things for market, consuming things already available
from various markets. Each must embrace the concept of consumer as
king/queen, or else risk undermining everyone's economic viability (i.e.
a slippery slope toward the absolute bureaucracy of socialist
totalitarianism whether it happens to resemble Soviet-style bureaucracy
or zwangswirtschaft-style bureaucracy).
Bottom line: this is a user mailing list, which makes it a mailing list
catered toward OFBiz consumers. When consumers encounter implications
that they are not the most important consideration, they become inspired
to take their business elsewhere (at least until encroaching
totalitarianism precludes such options as things become more bureaucratic).
On 17-11-17 01:34 AM, Taher Alkhateeb wrote:
> I went through the material (thank you again for sharing) and I have a
> few additional thoughts to share.
>
> Primarily I think there is no silver bullet, and there is no solution
> that somehow makes documentation "Fun". It's always going to be a
> liability that just comes with any software solution. With that being
> said, I would argue that a guide-based vs feature-based documentation
> is not necessarily mutually exclusive. You can have both and they
> complement each other.
>
> So maybe we should consider designing documentation such that:
> - Guides are good, we need a few good ones for common scenarios (hello
> world, new component. deployment, security, caching, etc ...)
> - Reference material is also good, possibly broken down by feature / module.
> - Everything should ideally be as short and concise as reasonably possible,
> - Content reuse should be applied as much as possible.
> - Documentation needs to constantly evolve (add, change and especially _REMOVE_)
>
> A good example for documentation I always like to use is Gradle [1].
> They really have fantastic documentation and I use ALL OF IT. I used
> the guides many times, but I also constantly look at the DSL
> reference. And when I am trying to implement an advanced feature, I
> roll my sleeves and start digging into the API documentation.
>
> To summarize, I think perhaps we should consider the following types
> of documentation as beneficial:
> - Focused guides (to achieve a specific task)
> - Reference documentation (not necessarily covering 100% of everything)
> - API documentation (auto generated from source code)
>
> [1] https://gradle.org/docs/
>
> On Thu, Nov 16, 2017 at 9:05 AM, Jacques Le Roux
> <ja...@les7arts.com> wrote:
>> Le 16/11/2017 à 06:34, Woosang Jung a écrit :
>>> On 2017-11-15 10:10, Jacques Le Roux <ja...@les7arts.com> wrote:
>>>> Le 15/11/2017 à 17:54, Jacques Le Roux a écrit :
>>>>> This is more for users I guess? Could the technical documentation be
>>>>> based on the same?
>>>> I read a bit more and now clearly understand that it's applicable to all
>>>> (user, technical, etc.)
>>>>
>>>> Jacques
>>> I'm all for it. How do I let you know what my main user stories are? Do I
>>> add to this thread?
>>>
>>> Woosang
>> Hi Woosang,
>>
>> Here are several possible ways for providing your user stories, by order of
>> preference:
>>
>> 1. If you are a registered wiki contributor (recommended) and want to format
>> them in Confluence (easier for us), look at the wiki pages I referred
>> above and see if a new page is needed. If you need, create a new page and
>> add you user stories there else use an existing page
>> 2. If you are not a registered wiki contributor and don't want to be one,
>> you can still add your Confluence formatted user stories as comments in
>> existing pages. So if you need a new page you need to ask for its
>> creation before adding comments...
>> 3. If you don't want to provide Confluence formatted user stories then open
>> a Jira and add your unformatted user stories in a text file
>>
>> https://cwiki.apache.org/confluence/display/OFBIZ/OFBiz+Contributors+Best+Practices
>>
>> Thanks
>>
>> Jacques
>> PS:we will maybe need to update
>> https://cwiki.apache.org/confluence/display/OFBIZ/OFBiz+Contributors+Best+Practices
>> for how to document using information above and more...
>>
New Accounting Company
Posted by Craig Parker <cr...@fossfolks.com>.
I've created a bunch of GL accounts, and can see them when I go to
Global GL Settings and peek at the chart.
I'm trying to get into Organization GL Settings to set up a company that
will use the accounts, and I don't think "Create New Accounting Company"
is working correctly. I go there, pick my company name from the drop
down, hit the Create new accounting company buttons, and land on a
fairly blank Organization GL Settings page.
The console log sayeth, and I'm wondering if the PrimaryKeyFinder line
(5-6 lines up from the bottom) is my issue, the following:
2017-11-20 15:42:30,639 |http-nio-8443-exec-9
|ControlServlet |T|
[[[AdminMain(Domain:https://localhost)] Request Begun, encoding=[UTF-8]-
total:0.0,since last(Begin):0.0]]
2017-11-20 15:42:30,675 |http-nio-8443-exec-9
|ConfigXMLReader |I| controller loaded: 0.01s, 9 requests,
9 views in
file:/ofbiz/specialpurpose/birt/webapp/accounting/WEB-INF/controller.xml
2017-11-20 15:42:31,063 |http-nio-8443-exec-9
|ConfigXMLReader |I| controller loaded: 0.359s, 505
requests, 238 views in
file:/ofbiz/applications/accounting/webapp/accounting/WEB-INF/controller.xml
2017-11-20 15:42:31,104 |http-nio-8443-exec-9
|ConfigXMLReader |I| controller loaded: 0.03s, 45
requests, 22 views in
file:/ofbiz/framework/common/webcommon/WEB-INF/common-controller.xml
2017-11-20 15:42:31,115 |http-nio-8443-exec-9
|ConfigXMLReader |I| controller loaded: 0.0s, 0 requests,
0 views in
file:/ofbiz/framework/common/webcommon/WEB-INF/handlers-controller.xml
2017-11-20 15:42:31,128 |http-nio-8443-exec-9
|ConfigXMLReader |I| controller loaded: 0.002s, 4
requests, 0 views in
file:/ofbiz/applications/commonext/webapp/WEB-INF/controller.xml
2017-11-20 15:42:31,208 |http-nio-8443-exec-9
|ServiceDispatcher |T| Sync service
[accounting/acctgPrefPermissionCheck] finished in [65] milliseconds
2017-11-20 15:42:31,253 |http-nio-8443-exec-9
|ServiceDispatcher |T| Sync service
[accounting/setAcctgCompany] finished in [110] milliseconds
2017-11-20 15:42:31,254 |http-nio-8443-exec-9
|RequestHandler |I| Ran Event [service:#setAcctgCompany]
from [request], result is [success]
2017-11-20 15:42:31,257 |http-nio-8443-exec-9
|RequestHandler |I| Rendering View
[PartyAcctgPreference]. Hidden sessionId by default.
2017-11-20 15:42:31,261 |http-nio-8443-exec-9
|ServiceDispatcher |T| Sync service
[accounting/getUserPreferenceGroup] finished in [2] milliseconds
2017-11-20 15:42:31,342 |http-nio-8443-exec-9
|ServiceDispatcher |T| Sync service
[accounting/getVisualThemeResources] finished in [78] milliseconds
2017-11-20 15:42:31,356 |http-nio-8443-exec-9
|ScreenFactory |I| Got 27 screens in 0.011s from:
file:/ofbiz/applications/accounting/widget/GlSetupScreens.xml
2017-11-20 15:42:31,375 |http-nio-8443-exec-9
|ScreenFactory |I| Got 11 screens in 0.01s from:
file:/ofbiz/applications/accounting/widget/CommonScreens.xml
2017-11-20 15:42:31,386 |http-nio-8443-exec-9
|ScreenFactory |I| Got 1 screens in 0.009s from:
file:/ofbiz/applications/commonext/widget/CommonScreens.xml
2017-11-20 15:42:31,386 |http-nio-8443-exec-9
|PrimaryKeyFinder |I| Returning null because found
incomplete primary key in find:
[GenericEntity:PartyNameView][partyId,null()]
2017-11-20 15:42:31,486 |http-nio-8443-exec-9
|ServiceDispatcher |T| Sync service
[accounting/getLastSystemInfoNote] finished in [37] milliseconds
2017-11-20 15:42:31,508 |http-nio-8443-exec-9
|ScreenFactory |I| Got 26 screens in 0.014s from:
file:/ofbiz/framework/common/widget/CommonScreens.xml
2017-11-20 15:42:31,515 |http-nio-8443-exec-9
|ServiceDispatcher |T| Sync service
[accounting/getVisualThemeResources] finished in [1] milliseconds
2017-11-20 15:42:31,682 |http-nio-8443-exec-9
|ServerHitBin |I| Visit delegatorName=default,
ServerHitBin delegatorName=default
2017-11-20 15:42:31,742 |http-nio-8443-exec-9
|ControlServlet |T|
[[[AdminMain(Domain:https://localhost)] Request Done- total:1.103,since
last([AdminMain(Domain...):1.103]]
Re: Some Information for Creating Modular Documentation
Posted by Craig Parker <cr...@fossfolks.com>.
+1 -- I personally like a "cook book" but find that the recipe usually
isn't exactly what I need, and end up looking further (reference guide,
search engine, community, etc)
On 11/17/2017 04:34 AM, Taher Alkhateeb wrote:
> I went through the material (thank you again for sharing) and I have a
> few additional thoughts to share.
>
> Primarily I think there is no silver bullet, and there is no solution
> that somehow makes documentation "Fun". It's always going to be a
> liability that just comes with any software solution. With that being
> said, I would argue that a guide-based vs feature-based documentation
> is not necessarily mutually exclusive. You can have both and they
> complement each other.
>
> So maybe we should consider designing documentation such that:
> - Guides are good, we need a few good ones for common scenarios (hello
> world, new component. deployment, security, caching, etc ...)
> - Reference material is also good, possibly broken down by feature / module.
> - Everything should ideally be as short and concise as reasonably possible,
> - Content reuse should be applied as much as possible.
> - Documentation needs to constantly evolve (add, change and especially _REMOVE_)
>
> A good example for documentation I always like to use is Gradle [1].
> They really have fantastic documentation and I use ALL OF IT. I used
> the guides many times, but I also constantly look at the DSL
> reference. And when I am trying to implement an advanced feature, I
> roll my sleeves and start digging into the API documentation.
>
> To summarize, I think perhaps we should consider the following types
> of documentation as beneficial:
> - Focused guides (to achieve a specific task)
> - Reference documentation (not necessarily covering 100% of everything)
> - API documentation (auto generated from source code)
>
> [1] https://gradle.org/docs/
>
> On Thu, Nov 16, 2017 at 9:05 AM, Jacques Le Roux
> <ja...@les7arts.com> wrote:
>> Le 16/11/2017 à 06:34, Woosang Jung a écrit :
>>> On 2017-11-15 10:10, Jacques Le Roux <ja...@les7arts.com> wrote:
>>>> Le 15/11/2017 à 17:54, Jacques Le Roux a écrit :
>>>>> This is more for users I guess? Could the technical documentation be
>>>>> based on the same?
>>>> I read a bit more and now clearly understand that it's applicable to all
>>>> (user, technical, etc.)
>>>>
>>>> Jacques
>>> I'm all for it. How do I let you know what my main user stories are? Do I
>>> add to this thread?
>>>
>>> Woosang
>> Hi Woosang,
>>
>> Here are several possible ways for providing your user stories, by order of
>> preference:
>>
>> 1. If you are a registered wiki contributor (recommended) and want to format
>> them in Confluence (easier for us), look at the wiki pages I referred
>> above and see if a new page is needed. If you need, create a new page and
>> add you user stories there else use an existing page
>> 2. If you are not a registered wiki contributor and don't want to be one,
>> you can still add your Confluence formatted user stories as comments in
>> existing pages. So if you need a new page you need to ask for its
>> creation before adding comments...
>> 3. If you don't want to provide Confluence formatted user stories then open
>> a Jira and add your unformatted user stories in a text file
>>
>> https://cwiki.apache.org/confluence/display/OFBIZ/OFBiz+Contributors+Best+Practices
>>
>> Thanks
>>
>> Jacques
>> PS:we will maybe need to update
>> https://cwiki.apache.org/confluence/display/OFBIZ/OFBiz+Contributors+Best+Practices
>> for how to document using information above and more...
>>
Re: Some Information for Creating Modular Documentation
Posted by Jacques Le Roux <ja...@les7arts.com>.
Hi Taher,
Inline
Le 17/11/2017 à 10:34, Taher Alkhateeb a écrit :
> I went through the material (thank you again for sharing) and I have a
> few additional thoughts to share.
>
> Primarily I think there is no silver bullet, and there is no solution
> that somehow makes documentation "Fun". It's always going to be a
> liability that just comes with any software solution. With that being
> said, I would argue that a guide-based vs feature-based documentation
> is not necessarily mutually exclusive. You can have both and they
> complement each other.
Yes good idea: +1
> So maybe we should consider designing documentation such that:
> - Guides are good, we need a few good ones for common scenarios (hello
> world, new component. deployment, security, caching, etc ...)
Yes and have a sole place to start from. For instance, it's not complete but I like https://whimsy4.apache.org/ It was a real mess to find stuff
before that (using Google each time)
> - Reference material is also good, possibly broken down by feature / module.
> - Everything should ideally be as short and concise as reasonably possible,
> - Content reuse should be applied as much as possible.
Yep, and as we discussed already, and seem agreed, we should start by porting the online help (both used from local help button or as a whole in
cmssite) from DocBook to AsciiDoc
Maybe it's part of your POC?
Jacques
> - Documentation needs to constantly evolve (add, change and especially _REMOVE_)
>
> A good example for documentation I always like to use is Gradle [1].
> They really have fantastic documentation and I use ALL OF IT. I used
> the guides many times, but I also constantly look at the DSL
> reference. And when I am trying to implement an advanced feature, I
> roll my sleeves and start digging into the API documentation.
>
> To summarize, I think perhaps we should consider the following types
> of documentation as beneficial:
> - Focused guides (to achieve a specific task)
> - Reference documentation (not necessarily covering 100% of everything)
> - API documentation (auto generated from source code)
>
> [1] https://gradle.org/docs/
>
> On Thu, Nov 16, 2017 at 9:05 AM, Jacques Le Roux
> <ja...@les7arts.com> wrote:
>> Le 16/11/2017 à 06:34, Woosang Jung a écrit :
>>> On 2017-11-15 10:10, Jacques Le Roux <ja...@les7arts.com> wrote:
>>>> Le 15/11/2017 à 17:54, Jacques Le Roux a écrit :
>>>>> This is more for users I guess? Could the technical documentation be
>>>>> based on the same?
>>>> I read a bit more and now clearly understand that it's applicable to all
>>>> (user, technical, etc.)
>>>>
>>>> Jacques
>>> I'm all for it. How do I let you know what my main user stories are? Do I
>>> add to this thread?
>>>
>>> Woosang
>> Hi Woosang,
>>
>> Here are several possible ways for providing your user stories, by order of
>> preference:
>>
>> 1. If you are a registered wiki contributor (recommended) and want to format
>> them in Confluence (easier for us), look at the wiki pages I referred
>> above and see if a new page is needed. If you need, create a new page and
>> add you user stories there else use an existing page
>> 2. If you are not a registered wiki contributor and don't want to be one,
>> you can still add your Confluence formatted user stories as comments in
>> existing pages. So if you need a new page you need to ask for its
>> creation before adding comments...
>> 3. If you don't want to provide Confluence formatted user stories then open
>> a Jira and add your unformatted user stories in a text file
>>
>> https://cwiki.apache.org/confluence/display/OFBIZ/OFBiz+Contributors+Best+Practices
>>
>> Thanks
>>
>> Jacques
>> PS:we will maybe need to update
>> https://cwiki.apache.org/confluence/display/OFBIZ/OFBiz+Contributors+Best+Practices
>> for how to document using information above and more...
>>
Re: Some Information for Creating Modular Documentation
Posted by Taher Alkhateeb <sl...@gmail.com>.
I went through the material (thank you again for sharing) and I have a
few additional thoughts to share.
Primarily I think there is no silver bullet, and there is no solution
that somehow makes documentation "Fun". It's always going to be a
liability that just comes with any software solution. With that being
said, I would argue that a guide-based vs feature-based documentation
is not necessarily mutually exclusive. You can have both and they
complement each other.
So maybe we should consider designing documentation such that:
- Guides are good, we need a few good ones for common scenarios (hello
world, new component. deployment, security, caching, etc ...)
- Reference material is also good, possibly broken down by feature / module.
- Everything should ideally be as short and concise as reasonably possible,
- Content reuse should be applied as much as possible.
- Documentation needs to constantly evolve (add, change and especially _REMOVE_)
A good example for documentation I always like to use is Gradle [1].
They really have fantastic documentation and I use ALL OF IT. I used
the guides many times, but I also constantly look at the DSL
reference. And when I am trying to implement an advanced feature, I
roll my sleeves and start digging into the API documentation.
To summarize, I think perhaps we should consider the following types
of documentation as beneficial:
- Focused guides (to achieve a specific task)
- Reference documentation (not necessarily covering 100% of everything)
- API documentation (auto generated from source code)
[1] https://gradle.org/docs/
On Thu, Nov 16, 2017 at 9:05 AM, Jacques Le Roux
<ja...@les7arts.com> wrote:
> Le 16/11/2017 à 06:34, Woosang Jung a écrit :
>>
>> On 2017-11-15 10:10, Jacques Le Roux <ja...@les7arts.com> wrote:
>>>
>>> Le 15/11/2017 à 17:54, Jacques Le Roux a écrit :
>>>>
>>>> This is more for users I guess? Could the technical documentation be
>>>> based on the same?
>>>
>>> I read a bit more and now clearly understand that it's applicable to all
>>> (user, technical, etc.)
>>>
>>> Jacques
>>
>> I'm all for it. How do I let you know what my main user stories are? Do I
>> add to this thread?
>>
>> Woosang
>
> Hi Woosang,
>
> Here are several possible ways for providing your user stories, by order of
> preference:
>
> 1. If you are a registered wiki contributor (recommended) and want to format
> them in Confluence (easier for us), look at the wiki pages I referred
> above and see if a new page is needed. If you need, create a new page and
> add you user stories there else use an existing page
> 2. If you are not a registered wiki contributor and don't want to be one,
> you can still add your Confluence formatted user stories as comments in
> existing pages. So if you need a new page you need to ask for its
> creation before adding comments...
> 3. If you don't want to provide Confluence formatted user stories then open
> a Jira and add your unformatted user stories in a text file
>
> https://cwiki.apache.org/confluence/display/OFBIZ/OFBiz+Contributors+Best+Practices
>
> Thanks
>
> Jacques
> PS:we will maybe need to update
> https://cwiki.apache.org/confluence/display/OFBIZ/OFBiz+Contributors+Best+Practices
> for how to document using information above and more...
>
Re: Some Information for Creating Modular Documentation
Posted by Jacques Le Roux <ja...@les7arts.com>.
Le 16/11/2017 à 06:34, Woosang Jung a écrit :
> On 2017-11-15 10:10, Jacques Le Roux <ja...@les7arts.com> wrote:
>> Le 15/11/2017 à 17:54, Jacques Le Roux a écrit :
>>> This is more for users I guess? Could the technical documentation be based on the same?
>> I read a bit more and now clearly understand that it's applicable to all (user, technical, etc.)
>>
>> Jacques
> I'm all for it. How do I let you know what my main user stories are? Do I add to this thread?
>
> Woosang
Hi Woosang,
Here are several possible ways for providing your user stories, by order of preference:
1. If you are a registered wiki contributor (recommended) and want to format them in Confluence (easier for us), look at the wiki pages I referred
above and see if a new page is needed. If you need, create a new page and add you user stories there else use an existing page
2. If you are not a registered wiki contributor and don't want to be one, you can still add your Confluence formatted user stories as comments in
existing pages. So if you need a new page you need to ask for its creation before adding comments...
3. If you don't want to provide Confluence formatted user stories then open a Jira and add your unformatted user stories in a text file
https://cwiki.apache.org/confluence/display/OFBIZ/OFBiz+Contributors+Best+Practices
Thanks
Jacques
PS:we will maybe need to update https://cwiki.apache.org/confluence/display/OFBIZ/OFBiz+Contributors+Best+Practices for how to document using information above and more...
Re: Some Information for Creating Modular Documentation
Posted by Woosang Jung <dr...@gmail.com>.
On 2017-11-15 10:10, Jacques Le Roux <ja...@les7arts.com> wrote:
> Le 15/11/2017 à 17:54, Jacques Le Roux a écrit :
> > This is more for users I guess? Could the technical documentation be based on the same?
> I read a bit more and now clearly understand that it's applicable to all (user, technical, etc.)
>
> Jacques
>
>
I'm all for it. How do I let you know what my main user stories are? Do I add to this thread?
Woosang
Re: Some Information for Creating Modular Documentation
Posted by Jacques Le Roux <ja...@les7arts.com>.
Le 15/11/2017 à 17:54, Jacques Le Roux a écrit :
> This is more for users I guess? Could the technical documentation be based on the same?
I read a bit more and now clearly understand that it's applicable to all (user, technical, etc.)
Jacques
Re: Some Information for Creating Modular Documentation
Posted by Jacques Le Roux <ja...@les7arts.com>.
Thanks Sharan,
This is more for users I guess? Could the technical documentation be based on the same?
So we would need 1st to collect and, I guess more surely, to create the user stories on which to base our user documentation on, right?
I know we have some already, thinks like that, right?
https://cwiki.apache.org/confluence/display/OFBIZ/PIM+User+Stories,+Use+Cases,+and+Test+Cases
https://cwiki.apache.org/confluence/display/OFBIZ/Sales+Order+Management+User+Stories,+Use+Cases,+and+Test+Cases
Todos:
https://cwiki.apache.org/confluence/display/OFBIZ/Order+Fulfillment+Process+User+Stories,+Use+Cases+and+Test+Cases
https://cwiki.apache.org/confluence/display/OFBIZ/Customer+Relationship+Management+(CRM)+User+Stories,+Use+Cases,+and+Test+Cases
That's certainly the best long range way, but it will take some ;)
Jacques
Le 15/11/2017 à 16:11, Todd Thorner a écrit :
> Yes, that is best practice for documentation, thanks for sharing the links.
>
>
>
> On 17-11-15 06:29 AM, Sharan Foga wrote:
>> Hi All
>>
>> (I'm resending this message as the original message I sent this morning didn't get through to the mailing list. I seem to have an intermittent
>> problem with posting somehow ;-)
>>
>> I recently interviewed Robert Kratky, a Technical Writer from Red Hat about his presentation on documentation at the Open Source Summit in Prague a
>> few weeks ago. He has some good advice for us and anyone looking at writing good documentation. His talk was about how to move from feature based
>> documentation (which is what we have tended to do) to more user story based documentation that is driven more by how our users use the software.
>>
>> You can listen to the interview at the link below:
>>
>> https://wp.me/p8gHED-QF
>>
>> Please take a look at his presentation
>>
>> schd.ws/hosted_files/osseu17/5f/%28OSSEU%2017%29%20Going%20Modular-%20Turning%20Legacy%20Docs%20into%20User-Story-Based%20Content.pdf
>>
>> and also at the github repo with some guidelines for writing modular documentation,
>>
>> https://github.com/redhat-documentation/modular-docs
>>
>> So as our community continues in its documentation efforts I'd like to highlight that anyone can contribute and help by letting us know how you are
>> using OFBiz and what are your main user stories.
>>
>> Thanks
>> Sharan
>>
>>
>>
>
>
Re: Some Information for Creating Modular Documentation
Posted by Todd Thorner <tt...@infotinuum.com>.
Yes, that is best practice for documentation, thanks for sharing the links.
On 17-11-15 06:29 AM, Sharan Foga wrote:
> Hi All
>
> (I'm resending this message as the original message I sent this
> morning didn't get through to the mailing list. I seem to have an
> intermittent problem with posting somehow ;-)
>
> I recently interviewed Robert Kratky, a Technical Writer from Red Hat
> about his presentation on documentation at the Open Source Summit in
> Prague a few weeks ago. He has some good advice for us and anyone
> looking at writing good documentation. His talk was about how to move
> from feature based documentation (which is what we have tended to do)
> to more user story based documentation that is driven more by how our
> users use the software.
>
> You can listen to the interview at the link below:
>
> https://wp.me/p8gHED-QF
>
> Please take a look at his presentation
>
> schd.ws/hosted_files/osseu17/5f/%28OSSEU%2017%29%20Going%20Modular-%20Turning%20Legacy%20Docs%20into%20User-Story-Based%20Content.pdf
>
>
> and also at the github repo with some guidelines for writing modular
> documentation,
>
> https://github.com/redhat-documentation/modular-docs
>
> So as our community continues in its documentation efforts I'd like to
> highlight that anyone can contribute and help by letting us know how
> you are using OFBiz and what are your main user stories.
>
> Thanks
> Sharan
>
>
>
Re: Some Information for Creating Modular Documentation
Posted by Sanjay Yadav <sa...@hotwaxsystems.com>.
Nice. Thanks for sharing documentation best practice.
Best Regards,
*Sanjay Yadav* | Manager, Enterprise Quality Assurance
HotWax Commerce <http://www.hotwax.co/> by HotWax Systems
<http://www.hotwaxsystems.com/>
80, Scheme No. 78, Part II, Indore, M.P. 452010, India
Mobile Phone: 787 918 8830 | Linkedin: Sanjay-Yadav
<https://www.linkedin.com/in/sanjay-yadav/>
On Wed, Nov 15, 2017 at 7:59 PM, Sharan Foga <sh...@gmail.com> wrote:
> Hi All
>
> (I'm resending this message as the original message I sent this morning
> didn't get through to the mailing list. I seem to have an intermittent
> problem with posting somehow ;-)
>
> I recently interviewed Robert Kratky, a Technical Writer from Red Hat
> about his presentation on documentation at the Open Source Summit in Prague
> a few weeks ago. He has some good advice for us and anyone looking at
> writing good documentation. His talk was about how to move from feature
> based documentation (which is what we have tended to do) to more user story
> based documentation that is driven more by how our users use the software.
>
> You can listen to the interview at the link below:
>
> https://wp.me/p8gHED-QF
>
> Please take a look at his presentation
>
> schd.ws/hosted_files/osseu17/5f/%28OSSEU%2017%29%20Going%20M
> odular-%20Turning%20Legacy%20Docs%20into%20User-Story-Based%20Content.pdf
>
> and also at the github repo with some guidelines for writing modular
> documentation,
>
> https://github.com/redhat-documentation/modular-docs
>
> So as our community continues in its documentation efforts I'd like to
> highlight that anyone can contribute and help by letting us know how you
> are using OFBiz and what are your main user stories.
>
> Thanks
> Sharan
>
>
>