Hi Olivier,
Sorry, in a hurry (must go now), I have a "Documentation" group of tabs and,
apart yours, mostly remain and its content.
OFBIZ-10285 OFBiz Documentation Global Task"
Hope you don't mind, I have converted the 2 Jiras below to be subtasks of it.
I have also to completely review the thread here (https://markmail.org/message/xtozirkgaotsqb34 ). To be sure we are not missing anything, help
appreciated ;)
I have also pending for a long time OFBIZ-10390 New documentation for EntitySync
BTW, what is the status of OFBIZ-11036 and OFBIZ-10251?
Thanks
Jacques
Le 05/10/2020 à 15:30, Olivier Heintz a écrit :
Hi all,
First step for migration from docbook to asciidoc seem to be done.
All help files and documentations files have been migrated and all help link
are now for html files generated from asciidoc.
If someone see a link which still go a the old help system, open a Jira or a
message on the mailing-list.
The Jira OFBIZ-11587 will be closed after all ...HelpData.xml will be removed
There are still some points to do for the help system migration:
* OFBIZ-11364 OFBiz Documentation System, How to write it
* OFBIZ-12030 Help System can be on user language
If you know some JIRA relative to documentation, please check if they have the Label
"Documentation"
About other Documentation Jira
There are few minor things and some others more systemic. What are your thought
about them? Take your time ;)
Among the minor issues:
====================
https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML:
This is now broken. I guess after you removed some files referenced by
documents in /plugins/cmssite/documents
Related with OFBIZ-11364 I guess.
Currently, there is no more demo available, and ofbizextra one have not the
cmssite plugin installed, so I will put it and check
OFBIZ-6243:
Having a README.md in each component ?
I don't think it's a good idea to have documentation in multiple format,
so I propose to replace them by a README.adoc with only one line with a link to
the user-manual.
I will check if for each component, content of current README.md is in
component intrduction in user-manual.
Among the more serious ones:
=========================
OFBIZ-10285:
What are your thoughts about this one (sorry not enough time to dig in)?
I propose to close this task, and check if all sub-task have the Documentation
label associated
if needed I will create new one for ofbiz-architecture schema
Also we need to update, actually mainly prune, the wiki, there is too much
deprecated and MISLEADING documentation there!
First finish / closed the more obvious Jira, ex: OFBIZ-11364 to have a clear
and up to date rules about where and how write documentation with which
conventions
Le 29/08/2020 à 17:09, Jacques Le Roux a écrit :
Note: weirdly we have almost no documentation in source for ecommerce
Le 29/08/2020 à 12:03, Jacques Le Roux a écrit :
Hi,
Some update here...
Le 17/07/2020 à 09:46, Jacques Le Roux a écrit :
Hi All, Olivier,
Again Olivier, I must say I'm so glad that you took the documentation challenge
in hands. That's very promising for the future of the project.
Thanks for your work!
At this stage I'd like to clean the situation as much as possible. It's not
about your work, but about all that we have left behind us. It's
difficult to figure out what the situation really is.
There are few minor things and some others more systemic. What are your thought
about them? Take your time ;)
Among the minor issues:
====================
I think we should begin to close issues like:
OFBIZ-6644:
This is deprecated with its sub-tasks
Done
OFBIZ-11893:
Trivial issues I collected before forgetting them. You might found more.
Updated with more info
https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML:
This is now broken. I guess after you removed some files referenced by
documents in /plugins/cmssite/documents
Related with OFBIZ-11364 I guess.
WIP by Olivier...
OFBIZ-9926 should be closed.
Done
OFBIZ-6243:
Should we take the burden of migrating the existing README.md?
I don't think so. I'd like to remove them with the related wiki pages, like:
https://cwiki.apache.org/confluence/display/OFBENDUSER/Financial+Accounting+and+Reporting
All that is mostly deprecated and redundant.
I have updated or removed deprecated information in README.md files.
I started with wiki pages but almost all of them will be moved to wiki attic
with OFBIZ-11619
Did not have time to continue on the rest below....
Jacques
Among the more serious ones:
=========================
OFBIZ-10285:
What are your thoughts about this one (sorry not enough time to dig in)?
It's clearly time to prune the sub-tasks, I mean close them if possible, like:
OFBIZ-10251
OFBIZ-10255
OFBIZ-11364
etc.
Also we need to update, actually mainly prune, the wiki, there is too much
deprecated and MISLEADING documentation there!
A bit of pontification :):
One thing I learned is that it's hard to maintain a documentation. Because
things evolve and are not always related to each other (like code).
So we should restrain ourselves to refer to things that may disappear or change
in the future. If not possible we need to generalise them as much
as possible.
An example is OFBIZ-6243.
Jacques
