Toshiya, Sorry for the late reply and making you wait.
> 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? Yes, this would be "immutable docs". That has a consequence of us not being able to fix mistakes on past releases, as docs are bound to a release. Good part is that we can easily automate that process and have references to exactly what was written in docs for each of our releases. The counterpart here would be "mutable docs", where we treat our documentation as a "live" repository, where every commit gets pushed to a published website, so users can experience the docs as we update them. This of course would mean that in the same branch we maintain multiple streams of our docs, like "10.0.x", "10.1.x", and "main", for example, as those all need to be available. Which already brings us to the "granularity" discussion. > 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). We have the same understanding regarding what a "stream" is, and this has a big impact on how we structure our docs. When users go search for something, will they have access to their EXACT release, like `10.0.2`, or will they have to point to their current stream, like `10.0.x`? I guess my personal preference leans towards the "stream" granularity, given we have a section describing exactly what changed between patches, like "fixes in 10.0.1", then "fixes in 10.0.2" etc. To conclude, I guess I can share my opinion on how I would like to see our docs structured/operated. - kie-tools/docs/drools - kie-tools/docs/optaplanner - kie-tools/docs/jbpm - kie-tools/docs/kogito - kie-tools/docs/sonataflow - kie-tools/docs/tools Each using whatever technology that they want inside their directory. Each stream with a daily-dev [1] automation (which publishes https://sandbox.kie.org/dev daily, for example), which would be published daily for each of those streams (main, 10.0.x, 10.1.x, etc). https://kie.apache.org would gain a new section called "Documentation" at its header, where you would be able to select what stream of the docs you want to see, for example: "Documentation" -> "main" -> "Drools". This would allow us to have documentation be mutable (websites updated daily) while also aligned with our branching and tagging strategy for releases. The tools necessary to contribute to all docs are already pretty similar to the ones needed by `kie-tools`. Atomic commits between features and docs would be possible for `sonataflow` and `tools`, and contributions for only docs would not need to install the other tools we need for the rest of the repo (like Docker), given `kie-tools`'s ability to do partial builds. PR checks would also automatically be non-dependent of the rest of the repo, checking only whatever packages changed in the PR, making them very fast. I would be happy to make this a reality myself, from migrating all repos to their individual packages (while keeping Git history) to updating our `daily-dev` automation to include pushing docs to https://kie.apache.org. [1] https://ci-builds.apache.org/job/KIE/job/kie-tools/job/main/job/kie-tools-daily-dev-publish/ On Fri, Jan 24, 2025 at 10:08 AM Toni Rikkola <trikk...@redhat.com> wrote: > > The solution that is possible depends on who can work on this and how much > time they have. For this reason it might be reasonable to include who does > what to get documentation work done in the vote. To make sure each party is > aware what work is needed from them and by when. This might affect the vote > result. > > I know there are a lot of moving parts and this would be one more, but > while Toshiya is driving this discussion, we all need to step up for the > task. > > Toni > > On Fri, Jan 24, 2025 at 10:54 AM Toshiya Kobayashi < > toshiyakobaya...@gmail.com> wrote: > > > Hi Tiago, > > > > Just in case you forgot this thread. Sorry about pinging while we > > already had a chat that you will answer to the Mutability and Granularity > > questions this week. > > > > I think I'll take a vote for this topic early next week. I note your point > > "We need a clearer and more detailed plan on providing documentation" and > > we can go into details after the vote about the direction. > > > > Regards, > > Toshiya > > > > > > On Tue, Jan 14, 2025 at 4:50 PM Toshiya Kobayashi < > > toshiyakobaya...@gmail.com> wrote: > > > > > 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 > > >>> > > >>> > > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@kie.apache.org For additional commands, e-mail: dev-h...@kie.apache.org
