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
<jacques.le.r...@les7arts.com> wrote:
Le 16/11/2017 à 06:34, Woosang Jung a écrit :
On 2017-11-15 10:10, Jacques Le Roux <jacques.le.r...@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...
