Thank you for starting this important conversation, Toshiya! As mentioned, unfortunately today our docs are dysfunctional and outdated.
First thing that we need to keep in mind is that we are Apache KIE and not individual projects. With this premise, I’d expect we consolidate all docs under a single structure that can be organized by domain (decision, optimization, workflow, serverless, satellite services). I’d also expect that whatever tech we choose, it complies with Apache. On Wed, Dec 18, 2024 at 3: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 > > > > > > > > > >
