You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ofbiz.apache.org by Olivier Heintz <ho...@apache.org> on 2020/10/05 13:30:48 UTC
Re: Documentation "issues" Status
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
>>>
Re: Documentation "issues" Status
Posted by Jacques Le Roux <ja...@les7arts.com>.
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
>>>>