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