[
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)
