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