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
<[email protected]> wrote:
Le 16/11/2017 à 06:34, Woosang Jung a écrit :
On 2017-11-15 10:10, Jacques Le Roux <[email protected]> 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...
