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 <jozef.ma...@ibm.com.invalid> > 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 > > > > jozef.ma...@ibm.com > > > > > > > > ________________________________ > > From: Toshiya Kobayashi <toshiyakobaya...@gmail.com> > > Sent: Wednesday, December 18, 2024 8:32 AM > > To: dev@kie.apache.org <dev@kie.apache.org> > > 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 < > > 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
