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
