+ 1 for Tiago's proposal... seems to provide a good compromise. In the long run, I'd prefer that we have an unified structure, but I also understand this would take much longer and I'm good to see progress!
I commit myself to help Tiago with that. On Fri, Jan 24, 2025 at 10:04 AM Tiago Bento <tiagobe...@apache.org> wrote: > > 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 > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@kie.apache.org For additional commands, e-mail: dev-h...@kie.apache.org
