Agree with Paolo. It does not make sense to move docs to kie tools. There is tendency to try to move everything to kie tools for some reason and the majority of contributors have already disagreed with this approach in one way or another. I would suggest to keep the repo isolated. Please rearrange the current doc repo without mixing the monorepo multirepo discussion again or it will get a disagreement by side topics not really related to the problem.
El lun, 27 ene 2025, 10:52, Toshiya Kobayashi <toshiyakobaya...@gmail.com> escribió: > > Tiago and I worked on a joint proposal that we’ll send later today, which > will include docs. > > > > I’d recommend withdraw this to avoid confusion. > > Thanks, that is much better. I deleted the proposal. > > Toshiya > > > On Mon, Jan 27, 2025 at 6:38 PM Alex Porcelli <porce...@apache.org> wrote: > > > Toshiya, > > > > Tiago and I worked on a joint proposal that we’ll send later today, which > > will include docs. > > > > I’d recommend withdraw this to avoid confusion. > > > > - > > Alex > > > > On Mon, Jan 27, 2025 at 1:57 AM Toshiya Kobayashi < > > toshiyakobaya...@gmail.com> wrote: > > > > > Thank you very much for the detailed proposal, Tiago. > > > > > > As suggested in another thread, I wrote it as a [PROPOSAL] page in the > > > apache KIE wiki. > > > > > > > > > > > > https://cwiki.apache.org/confluence/display/KIE/%5BPROPOSAL%5D+KIE+Documentation > > > > > > It's a little odd that I write your proposal, but I hope you are fine > > with > > > it. Please modify the proposal page as you want. > > > > > > If there is no further discussion, I will raise a [VOTE] thread for the > > > proposal some time soon. > > > > > > Thanks! > > > Toshiya > > > > > > On Sat, Jan 25, 2025 at 12:30 AM Alex Porcelli <a...@porcelli.me> > wrote: > > > > > > > + 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 > > > > > > > > > > > > > >
