[jira] [Commented] (OFBIZ-6243) Have a readme in every component

[Nicolas Malin (Jira)]

    [ https://issues.apache.org/jira/browse/OFBIZ-6243?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15444191#comment-15444191 ]

Jacques Le Roux commented on OFBIZ-6243:
----------------------------------------

bq. Did we discuss all of this before?
Not much, this effort started already more than 1 year ago. At this point it looked like a good idea to me because it was simple and added content and links. Nobody reacted negatively, so lazy consensus applied.

I agree that we need to better organise our documentation. But what is and will be  our documentation are the 1st questions we should ask. Let me try to summarize.
*Currently:*
# I believe we will anyway need a wiki, for several reasons (eg ASF provides it), Confluence seems to fit. We "simply" need to prune and organise there. I envision it more as a complement to our HTML main site. A mean to hook to our more complete documentation, a middle part if you want, with also its own convenient versioning and history.
# We need an online and contextual documentation. So far we have used Docbook for that
* Contextual: Help button/component (incomplete and not really looking good, webhelp at OFBIZ-6644 was an effort to make it looking better)
* Online:  https://ofbiz-vm.apache.org:8443//cmssite/cms/APACHE_OFBIZ_HTML (slow and incomplete, but a doc will always be incomplete), this is too much neglected, to be reused as much as possible.

*Futur*
Now we want to complete and organise our documentation better with a format that still needs to be defined. One thing we should really take care from start is not only the format but also the free editor for that format to use. I like asciidoc, but dita is also interesting because of its feature to easily reuse contents. I found 2 editors in this article (more a reminder for myself here)  https://writing-technical.blogspot.fr/2010/09/dita-tools-4.html

*For you other questions*
bq. If we do proceed with this documentation what do we do with these README files? Do we delete them? update them?
We should reuse (improve if needed) as much as possible content and links when they exist, being in readme, wiki, dockook, etc.

bq. Do they only contain this wiki link or do they contain more documentation?
So far the documentation is mostly in the wiki page linked (Pierre correct me if I'm wrong)

bq. What is enough to go into these README files as opposed to other documentation tools / resources?
I think that few sentences and links are enough. Either to the wiki or rather eventually to the online doc. (possibly using anchors), with a genetal parameter to define the server to use (default to trunk demo is maybe not a good idea, it should be more reactive)
For now, eg https://svn.apache.org/repos/asf/ofbiz/trunk/specialpurpose/lucene/README

As you can see, I believe we should not drop all what we have and restart from scratch.

Ah and finally, for memory also, Pandoc is a wonderful tool! We could use it to have different persons using different formats, but eventually contributing in the format the OFBiz project will choose.

> Have a readme in every component
> --------------------------------
>
>                 Key: OFBIZ-6243
>                 URL: https://issues.apache.org/jira/browse/OFBIZ-6243
>             Project: OFBiz
>          Issue Type: Improvement
>          Components: ALL COMPONENTS
>    Affects Versions: Trunk
>            Reporter: Pierre Smits
>            Assignee: Jacques Le Roux
>             Fix For: Upcoming Branch
>
>
> A readme should be the first starting point of each component for developers have references to the placeholder in the wiki, in jira and in svn/viewvc

--
This message was sent by Atlassian JIRA
(v6.3.4#6332)