Thank you for the comments. As Tiago noted, we will wait for more people and opinions.
In the meantime, I have raised a thread in general@incubator ML asking about requirements for documentation. https://lists.apache.org/thread/gzsp56p9p2z5zyfggw4ox2l71wjyjmhs Cheers, Toshiya On Wed, Dec 18, 2024 at 11:23 PM Tiago Bento <tiagobe...@apache.org> wrote: > Hi Toshyia and all! > > Thanks for creating this thread and starting the discussion on how to > move forward with our docs! > > As much as I understand the issue we brought upon our users with the > 10.0.0 release not having up-to-date documentation, I think we need a > clearer and more detailed plan on how to solve this for good for 10.1 > and beyond. > > For those who followed the saga on the 10.0.0 release, you know that > everything started with a rather intense discussion here at dev@ > before it then evolved into a document that took a few weeks to be > completed and put into execution. > > I suggest we follow the same approach for documentation/websites. > Let’s wait for more people to get involved and voice their opinion > before we can have a holistic view of the problem and draft a first > execution plan. Once we’re fine with it, we can move into a PROPOSAL > and, if necessary, a VOTE. > > Let’s also consider we’re in a period of the year where many people > are vacationing and spending time away from contributing everyday. So > I guess we’ll need to be a little more patient than usual in that > regard. (I know this was already said above, and I apologize for being > repetitive… just highlighting this point for us to not make the same > mistakes we made in the past with adopting half-measures that end up > biting us later on). > > As for the documentation itself, here's my take: > > - I’m all for consolidating our documentation inside a single place > (repo) that will allow us to refactor more easily once we’re set on > the approach we want to follow, structure-wise. No preference for > frameworks or tools, just that we don't overload it with indirection > and abstractions, making it the most plain-text possible. Dumb > find-and-replace should be enough for refactoring it. > > - 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. > > - I don't think we should manually publish docs for 10.0.0. Instead, > we should use our time to define how we want our docs to look like for > the medium/long term and work towards a 10.1 as soon as possible, > already including docs. Because we spent so much time developing > without necessarily updating our docs, 10.0.0 docs might be wrong > and/or outdated, which will result on demand from us to update it and > fix it, taking away resources we could be using towards a better 10.1 > release including docs. > > - As Alex said, I'd much rather prefer we had > https://kie.apache.org/docs/<version> instead of > https://kie.apache.org/docs/<project>/<version>/. Drools, jBPM, > Kogito, SonataFlow, OptaPlanner, IMHO should all have their own > sections on the docs, especially to define what they are, but not have > a completely independent, top-level status. The biggest advantage of > Apache KIE, IMHO, is the integration between all its > libraries/tools/apps, so having them be separate 'silos' I'm afraid > would encourage us to keep somewhat segregated and eventually deviate > too much in regards to quality, format, content, structure etc. Those > who've been working more closely with me know that I'm a big advocate > for flat structures and composition, and the way I see our docs is not > different. *Composing* our libraries/tools/apps is what makes us > really shine. > > - Our plan should include considerations on how to contribute/develop, > and report issues for our docs, taking into account that people who > consume our software and docs may not necessarily have the skill set > to develop everything else. > > - Last, but not least, I think we should really think about not adding > too much automation and instead try "plugging" into the processes we > already have. We all know maintaining pipelines has been our Achilles' > heel. > > Kind regards, > > Tiago Bento > > > On Wed, Dec 18, 2024 at 5:21 AM Dominik Hanak <domin.ha...@gmail.com> > wrote: > > > > Hi Toshiya, > > > > what you wrote sounds reasonable. > > > > Imho we should agree on where to have the source code of documentation > > first. > > Current approach of having it split suits me, but might not be suitable > for > > everyone or because of other, yet unknown, reasons. > > This has an impact on how we upload and update the documentation, if we > > have it split the updates might be tricky without some proper > > automation as you are suggesting. > > > > Hosting afaik, needs to be under apache so we do not have much room to > > wiggle here. Will double check with your sources and > > other projects that are incubating. > > > > Lastly, some of the components need extensive updates, so we should > capture > > issues required for the individual component documentation > > to be useful for users. > > > > We could also dedicate some time to this on Friday call. > > > > Regards, > > > > Dominik > > > > > > > > > > > > On Wed, 18 Dec 2024 at 09:01, Paolo Bizzarri <pibi...@gmail.com> wrote: > > > > > Hi Toshiya, > > > > > > thank you for taking care of this. > > > > > > I agree with your suggestions. These seem quite reasonable. > > > > > > The only issue is if there are specific requirements from apache on the > > > structure of the docs. > > > > > > I do not think so, but let's check just to confirm this. > > > > > > I will review the links you have provided to see if there are any > > > indications related to docs. > > > > > > Regards > > > > > > Paolo > > > > > > > > > On Wed, Dec 18, 2024 at 8:32 AM Toshiya Kobayashi < > > > toshiyakobaya...@gmail.com> wrote: > > > > > > > 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 > >
