Hi,
I think it's great that you are migration your docs to AsciiDoc.
What are you using to publish them?
We've been working on doing a similar process in Apache James.
We decided to use Antora for publishing the content which is pretty
great so far.
We haven't finished our process.
I've managed to make the automated build and the next goal is to work on
the content and structure.
If you are interested, here are some links:
* https://github.com/apache/james-site/ - repo to build the
documentation website - includes gradle tasks to build the theme and run
antora.
* Jenkinsfile is used to publish the staged website to
https://james.staged.apache.org/main/3.5/index.html
* https://issues.apache.org/jira/browse/JAMES-3226 Jira issue to track
the progress
La 20.07.2020 11:54, Olivier Heintz a scris:
Thanks Jacques, for this list,
I will finish the plugins docbook migration to asciidoc
and I will continue with these JIRA, with a first step to be sure to migrate
all old format to the new one.
This list is a good road to clean before doing some new doc.
Thanks
Olivier
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
OFBIZ-11893:
Trivial issues I collected before forgetting them. You might found more.
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.
OFBIZ-9926 should be closed.
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.
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
--
Eugen Stan
+40720 898 747 / netdava.com