Hi, I have a comment that may look unrelated, but it is related to the technology we choose.
In the past we often used pictures [1] for documenting different things as procedures, configurations, source code examples and much more. In my opinion we should decrease the use of pictures generally. - The pictures git diff may be not easy to review in PR - Pictures are not searchable, picture may contain example of property 'abc', however Ctrl+F will not search in picture for 'abc' - Content from pictures cannot be copied and pasted - Developers usually do not have a knowledge, if there is a documentation affected by their changes in (drools, kogito-runtimes, kie-tools ...) and pictures start to be outdated after their PR is merged - as pictures are not searchable We should adopt technology (I do not know mentioned Antora, maybe it fits all points I mention) that: - Allows to generate code snippets with easy copy and paste feature - Allows to generate code snippets stored elsewhere, we should avoid creating 'TrafiicViolation.dmn' again - Allows to generate code snippets that are readbale without scrolling - snippets displayed on reasonable display size - Allows to generate documentation that is searchable as in website so in pdf - Allows to generate output that is compatible with AI assistants. [1] https://docs.jbpm.org/latest/jbpm-docs/html_single/#_creating_the_applicant_data_object jBPM Documentation<https://docs.jbpm.org/latest/jbpm-docs/html_single/#_creating_the_applicant_data_object> jBPM is a flexible Business Process Management (BPM) Suite. It is light-weight, fully open-source (distributed under Apache License 2.0) and written in Java. docs.jbpm.org Jozef Marko Software Developer jozef.ma...@ibm.com ________________________________ From: Toshiya Kobayashi <toshiyakobaya...@gmail.com> Sent: Wednesday, December 18, 2024 8:32 AM To: dev@kie.apache.org <dev@kie.apache.org> Subject: [EXTERNAL] Re: [DISCUSS] KIE documetation Hi, No one has yet replied, but I believe many people care about documentation. While "B) Automation" and "C) Consolidate docs projects" may require some time and discussions, can we agree with some points below? * KIE projects documentation should be hosted under https://kie.apache.org/ . For example, https://kie.apache.org/docs/ <project>/<version>/ * Automation should be eventually required, but for 10.0.0 docs, we may manually commit docs to https://github.com/apache/incubator-kie-website/ * Docs generation tools should be discussed, but until a decision is made, we can use the current tool (e.g. Antora). Any thoughts? # I guess, many of us are already on holiday. Not rushing... Toshiya On Mon, Dec 16, 2024 at 4:47 PM Toshiya Kobayashi < toshiyakobaya...@gmail.com> wrote: > Hello all, > > Here is a discussion thread for documentation. > > This might be related to website, but let's mainly focus on documentation. > > So far, each project has its own repo or module to generate its > documentation and publish it. > > incubator-kie-drools/drools-docs : using antora > incubator-kie-optaplanner/optaplanner-docs : using antora > incubator-kie-kogito-docs (sonataflow) : using antora > incubator-kie-docs:master-kogito (kogito) : using asciidoctor > > Topics to discuss are: > > A) Hosting documentation > > - For example, Host those documentations under https://kie.apache.org/ > > B) Automation > > - For example, Create GHAs to generate docs, commit them to > incubator-kie-website, and rebuild incubator-kie-website to make them > available > > C) Consolidate docs projects > > - Do we want to move docs projects to the same place? > - Do we want to use the same technology for docs? > FYI, antora is MPL-2.0 , asciidoctor is MIT License > > The above are just some thoughts that came to mind. > > Feel free to share your thoughts and start the discussion. > > Btw, Here are some links about website for apache projects. However, I > can't find much about documentation. > > https://incubator.apache.org/guides/sites.html > https://infra.apache.org/project-site.html > https://infra.apache.org/website-guidelines.html > > Thanks! > Toshiya >
