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 < [email protected]> 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 < > [email protected]> 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 <[email protected]> >> 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 <[email protected] >>> > >>> > 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 >>> > > >>> > > [email protected] >>> > > >>> > > >>> > > >>> > > ________________________________ >>> > > From: Toshiya Kobayashi <[email protected]> >>> > > Sent: Wednesday, December 18, 2024 8:32 AM >>> > > To: [email protected] <[email protected]> >>> > > 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 < >>> > > [email protected]> 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: [email protected] >>> For additional commands, e-mail: [email protected] >>> >>>
