On 2024/12/18 14:16:47 Alex Porcelli wrote: > 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.
+1 > 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). Good idea. > I’d also expect that whatever tech we choose, it complies with Apache. What we build the docs with should not be a concern. We don't release documentation as part of the source, and even if we did, it is the source code of the documentation. How we go from some format to HTML on a web server shouldn't matter to the project, release, IPMC. > On Wed, Dec 18, 2024 at 3:21 AM Dominik Hanak <[email protected]> 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 <[email protected]> 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 < > > > [email protected]> 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 < > > > > [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]
