Hello, I would also prefer a short In-App documentation and larger documentation "outside" . Personally, I prefer to read pdf documents so I can take additional notes. But HTML is also good for a quick online search.We must keep in mind what kind of documentation we want to create and should not mix them. Also, cross-references between the individual "chapters" should be avoided. This makes it easier if something should change.
1. Quick starter documentation. 2. Setup Documentation 3. Technical Documentation 4. User manual documentation with best practise I think we should hit the road and take a look along the way :) I know the in app documentation is in markdown so far?I would recommend to write the documentation in asciidoc [1] [2] This could be set up with asciidoctorj [3]. This makes it easy to include everything in Git and also keep the documentation alongside the source code. So if something is rewritten, the developer can also change the documentation. Makes new screenshots and deletes old ones.3] The creation of a PDF or HTML file can be done with Github Action. With every commit or with every release. The results can be pushed to the StreamPipes website, I guess? What do you think? Florian [1] https://docs.asciidoctor.org/asciidoc/latest/[2] German Source https://blog.ordix.de/docs-as-code-dokumentation-mit-asciidoctor[3] htt ps://github.com/asciidoctor/asciidoctorj Am Mittwoch, dem 24.08.2022 um 07:07 +0000 schrieb Dominik Riemer: > Hi, > yes, we can do both: In-app documentation which only covers the > configuration and a short description of the adapter and pipeline > element and additional step-by-step guides/tutorials with nice > screenshots that are available in the online documentation. We can > have such step-by-step guides for the most frequently used adapters. > @Florian, do you want to work on such a guide on the website? I know > you had some really good documentation ideas some while ago 😉 > CheersDominik > > -----Original Message-----From: Philipp Zehnder < > [email protected]> Sent: Sunday, August 21, 2022 1:07 > PMTo: [email protected] > Subject: [DISCUSS] Documentation - Description for Adapters and > Processing Elements > Hi all, > here is a new thread to discuss the adapter documentation.Here is a > link to the previous discussion in the release thread [1]. > @Dominik I know that the registration is different, but since all > adapters already have the three files (documentation.md, icon.png, > and string.en), shouldn’t it be possible to also display the > description in the UI.How are we doing currently for the icons? > Because they are loaded dynamically as well. I think the main > difference is that the icons are loaded directly from the worker > container and not from the backend. Couldn’t we do it similarly for > the documentation file? (Please correct me if I am wrong) > Regarding the description on the Website. I think it would be great > if we could generate this based on the markdown files for each > adapter. > The documentation.md files mostly describe the configuration > parameters of adapters and processors. I think it would be great to > have additional examples how to use them. (e.g. describe how a CSV > file is uploaded or how a PLC is connected). Should we include such > examples into the documentation.md file or should there be another > location for this? Any thoughts on that? > @Florian you wrote that you would like to work on the documentation. > If you need anything to start with, please let us know. > Cheers,Philipp > > > [1] https://lists.apache.org/thread/29w586db1btqo0ps1rgo3fscvt3tvrzg
