Hi all, I think we can have some more time for discussion before voting, but listing vote options would help to clarify the discussion so far.
Options per topic would be like: A) Hosting documentation 1. https://kie.apache.org/docs/ 2. other B) Docs structure 1. consolidate all docs under a single structure that can be organized by domain (decision, optimization, workflow, serverless, satellite services). 2. other C) Consolidate docs projects to "Where" 1. incubator-kie-website 2. incubator-kie-docs 3. incubator-kie-tools 4. other D) Docs generation tool 1. Antora 2. other X) Automation We can discuss this after deciding other topics (Note that Tiago warned about "too much automation") ==== Other discussed topics: - We need a clearer and more detailed plan on providing documentation - Tiago wrote about mutability and granularity. I'm not well understanding, so I'll send questions. - IPMC confirmed that docs generation tool's license doesn't need to be Apache compatible as long as it's not included in a release distribution ( https://lists.apache.org/thread/gzsp56p9p2z5zyfggw4ox2l71wjyjmhs) - Decrease the use of pictures - Jozef mentioned several requirements for doc tool (e.g. Allows to generate code snippets with easy copy and paste feature) ==== Feel free to add any options/discussions I missed. Thanks! Toshiya On Fri, Jan 3, 2025 at 11:51 PM Jason Porter <lightguar...@apache.org> wrote: > I think realistically we should have more context aware > documentation/tips/hovers/etc within sandbox itself instead of relying on > screenshots all over. Screenshots can be problematic for all the reasons > mentioned in this thread, they also are extremely difficult to recreate > even from the same contributor. > > As for code, honestly, I'd want code to be stored in a repo adjacent to > the docs repo, or even better, within the docs repo itself. There is 0 > reason we can't do things like including code that is right there. We can > even automate running the code with tests and what not to make sure it > still works. > > On 2025/01/03 10:30:53 Alex Porcelli wrote: > > Josef, > > > > If pictures mentioned are related to code snippets, I fully agree. > > > > However, it’s going to be very hard to write good docs for Sandbox or the > > editors without images. We had in the past an attempt to describe UI with > > words only and it felt very confusing. (To not mention that docs also got > > outdated, no matter of the use of text instead of image) > > > > - > > Alex > > > > On Fri, Jan 3, 2025 at 5:27 AM Jozef Marko <jozef.ma...@ibm.com.invalid> > > wrote: > > > > > 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 > > > > > > > > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@kie.apache.org > For additional commands, e-mail: dev-h...@kie.apache.org > >
