Hi Toago, you wrote: === - We need to collectively decide whether or not we want mutable or immutable documentation. I.e., whether we make our documentation a release artifact (immutable), or we maintain a parallel development environment/workflow for docs/websites with its own CI/CD pipelines (mutable). My personal preference is towards immutability, so docs would be integrated in our builds and releases and available on release candidates too. This wouldn't invalidate making docs from the `main` stream available to users too, as we can follow the same approach we do for Maven artifacts (999-SNAPSHOT), container images and https://sandbox.kie.org/dev.
- Regardless of the development workflow for docs/websites, we need all versions to have their own documentation available, but we need to define the granularity. I.e., would one separate documentation be used for each 10.0.x release? Or will we keep one documentation per stream and amend it based on patches that we end up making, like 10.0.1, 10.0.2, etc? My personal preference is towards the latter, making us only have to write migration guides between minor releases, and make it easier to know what's the diff between patches. === Sorry that I'm not very clear about that. Please help me to understand. * Mutability I can understand that we will generate and publish docs of a minor release version (e.g. 10.1.0) and we will not modify it. It's immutable, correct? Then, I think we don't need to deploy the document as "a release artifact" for maven. Am I misunderstanding your point? * Granularity You wrote "one separate documentation be used for each 10.0.x release" vs "one documentation per stream". What do you mean by "stream"? I thought that "stream" is a branch for each minor release, so it's equivalent to "10.0.x" branch (we call it development stream). Regards, Toshiya On Tue, Jan 14, 2025 at 4:26 PM Toshiya Kobayashi < toshiyakobaya...@gmail.com> wrote: > 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 >> >>
