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 > >
