[
https://issues.apache.org/jira/browse/OFBIZ-6243?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15444087#comment-15444087 ]
Taher Alkhateeb commented on OFBIZ-6243:
----------------------------------------
Hi Jacques,
First of all (and you seem to also agree) the effort to deliver what is being delivered would take something like 30 minutes to an hour for all components, all that I see is a one or two sentences after the apache header in each README file. Definitely as you said not worth drowning us in so many JIRAs. It takes more energy to start, update and close those JIRAs than it would to prepare one patch and get the whole thing delivered. Not to mention that having too many of those JIRAs just creates noise and gives false statistics.
But the question becomes .. why? what is the purpose? All that I see is a link to wiki page in each README file, and we were already discussing moving things away from wiki and into some kind of SCM probably utilizing something like dita, docbook or asciidoc. If we do proceed with this documentation what do we do with these README files? Do we delete them? update them? Do they only contain this wiki link or do they contain more documentation? What is enough to go into these README files as opposed to other documentation tools / resources? Did we discuss all of this before?
Answering these questions can at least shed light on whether this is a good move or not. To me, if these files just hold a wiki link, then I don't think it is worth it, just create a page in the wiki called "Ofbiz Components" and put a documentation page per component, no need to clutter the framework with all these files. If there is more documentation to go in, then what is it, and why in README files and not the other solutions discussed. If you remember from our discussion I recommended that we minimize the README files and focus on a powerful documentation tool and correct me if I'm wrong but I remember that you had a similar point of view.
> 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)
Locked
