kyma-project
Documentation for modular Kyma
Description
The concept of documenting modular Kyma is designed. The following scenarios (see Acceptance Criteria) should be taken into consideration (valid forr OS and SKR documentation).
Acceptance Criteria
- [ ] Documentation of existing Kyma components has to be reviewed in terms of possible changes coming from the new modular achitecture. Discrepancies has to be adjusted.
- [ ] Whenever possible, current structure of the documentation should be retained
- [ ] Cross-cutting subjects (getting started guides, installation) has to be described in the docs (relates to https://github.com/kyma-project/community/issues/700)
- [ ] Subjects specific to the new architecture (e.g module enable/disable) has to be described in the docs
- [ ] Module documentation should be decoupled from Kyma documentation (in case of deprecation/significant upgrades it would be easier to handle it)
Links
stacktrace of discussions on this subject: _Hi, We discussed in the PO round what to do with the documentation in the modularization context. Couple of questions we got: What to do with cross module documentation? Do we need scenario based guides at all? Maybe we should keep them independent? Do we need separate sections for operational guides, architecture & technical reference? Maybe simpler structure plus tagging? It was triggered by this thread: https://sap-btp.slack.com/archives/C01KSGZA23C/p1663143912856019 I wanted to have a quick chat with you about possible next steps, how to drive it and finally who should do it. I wanted to first get your opinion, before we start anything.
Cheers, PB_
_Hi, To sum up:
- The old navigation structure with modules listed on the left is preferred over the current layout.
- Each module should have (owns) its tutorial.
- We need to keep the ‘getting started’ section as an aggregate for the above tutorials (or a subset).
- Assumption: Components have their own separate repos;
- Documentation for each component is in the respective component's repo;
- Docs from all repos are consolidated on the Website, which serves as an entry point for the user.
- Tags as a complementary way of navigation
- Search is a must (it’s the key differentiator from GitHub)
- We need to involve Mariya for the UX proposals
- We need to involve Hasselhof/Varban as the current website owners for the implementation of above changes
Did I miss anything? Regards, Jacek_
stacktrace of discussions on this subject: _Hi PB,
- Are we going to create a strategy defining the relationship between OS and SKR docs, how we handle duplicated content vs. linking (and getting SKR readers stranded on the OS page…)?
- How is the 3-release-channel model planned to mesh with the continuous delivery setup for our SKR docs?
- How is the 3-release-channel model planned to mesh with the Unified Runtime (docu) strategy?
- Anything against reusing our old website structure? Of course, with adjustments to our current design.
Cheers, Jacek_
_Thanks PB for the talk, to sum up for everyone:
- We continue with our current approach to have documentation from OS referenced/linked in SKR docs.
- There seem to be no constraint from the modularization at our docs, we will “simply” adopt the new approach from the SKR docs. There will be two release channels: alpha and stable.
- UR docu strategy – no constraints from the modularization, here I will catch up with the respective UR docu people to sync our plans
- Nothing against adopting our old docu structure for the modules/components docus; As long as we have in parallel the task-based docu for the cross-cutting subjects e.g., getting started, installation, etc.
Thanks, Jacek_
- [ ] Mariya new UX proposal
- [ ] @majakurcius module template based on old information/documentation types but simplified for OS website. With support from @NHingerl @grego952 @IwonaLanger. And taking into account requirements from the comments above (tutorial in each, common properties optional:true/false, etc.)
- [ ] @NHingerl module template based on SAP Help Portal and BTP information structure. So we can leverage the new continous release process. Reuse our current clean docs for eventing.
- [ ] @valentinvieriu /Hasselhof: technical plan & implementation of the above
- [ ] @jacekon help portal documentation design / information structure behind
- [ ] @NHingerl @IwonaLanger @grego952 (and other TWs): if necessary, adaptation of existing documents into the new structure, and development of new docs.
stack trace of discussions on this project, from Maja:
_Hi!
Below is my understanding of point #1 as how I understood also @Bochynski, Piotr would see it, and then some additional things we talked about.
Re 1: I think if we want to go with the solution that I proposed on this oh so nicely drawn draft below (also attached) – i.e. the multiselect dropdown, from which you select individual components/a desired combination of components/ALL components (the first item on the list) – then:
- The documentation can be browsed by components. 1a. The left-side navigation resembles what we have now, but… 1b. …the document categories are further simplified (i.e. Operation Guides and Developer Tutorials are merged into one category: Tutorials; The subcategories under Technical References could also be simplified and/or tidied up). This leaves us with only 4 main categories + Glossary:
- Overview
- Get Started
- Tutorials
- Technical Reference Glossary 1c. This leaves us with a question: where do we move Troubleshooting and Security guides? Also to tutorials, under a dedicated sub-directory? Or would it be better to bring back separate main categories for these? @DL Kyma TW @Bochynski, Piotr …
- What about version on the Website? Tags and multiselect are fine if we only display the latest version. If we want to make it possible to select other versions (currently it’s 1/2 versions back or main, and pre-release), I imagine it either makes the version selection more complex (UX-wise? Probably something to consult with Mariya?), as it should be available to select for every component, and then also displayed for every component, or we have to give up multiselect? Unless we change the way we version the components – if we go with 2-3 release channels (like stable/regular/rapid), and display docs for all components for the same channel, then that should not be an issue, we just have another dropdown for the channel version, collectively (or something of this sort).
- To ease up the transition from getting started with Kyma to further exploring it, we add Related links to each of the Get Started guide that would take the user to the relevant, connected documentation (just not too many, not to cause information overload; maybe to the related component’s overview or sth).
- Tutorials that touch more than one component are written in the main component’s repo (and own by the repo owners), but are also replicated/linked to in the other component’s repo, because if a user prefers to browse documentation via GitHub rather than the Website and/or is only interested in a particular component, they might miss it otherwise. 13b. On the Website, such a document is nicely marked with the respective components’ tags (all the documents have tags, but such a tutorial with more “dependencies” is clearly spotted by having more than one component tag)._
After a talk with Aneta Peteva, Nikola Simeonov, Astrid Herbst - we can't have more than one release channel on sap's help. Only one is supported by the current information structure in BTP docu area.
After a talk with Aneta Peteva, Nikola Simeonov, Astrid Herbst - we can't have more than one release channel on sap's help. Only one is supported by the current information structure in BTP docu area.
Isn't this issue about the OS documentation on the https://kyma-project.io Website? It's also in the OS GitHub.
@jacekon about "Module template based on SAP Help Portal and BTP information structure."
I'm still not sure what is meant with "Module template".
We're going to put explanatory content in concept topics, and instructional content in task topics. The DITA standard has clear templates for those, no need to create them.
As for the information structure, we're bound to the BTP Core structure, which is sectioned with the following navigation nodes:
Basic Platform Concepts Getting Started Development Extensions Administration and Operations Security Getting Support Glossary
-
Thus, we should put any explanatory overview information about modular Kyma in the introductory concept topic about the Kyma environment. I expect this to be just a few paragraphs; but if it's longer we can simply create a child topic below Kyma Environment.
-
Information how to install and maintain modules is an Admin/Ops task, so that would become a new child topic under Administration and Operations in the Kyma Environment.
❓ I'm not sure what else we need? Looking at the email from Sept 6th, reviewing Kyma's overall content strategy for SKR docs is out of scope.
➡️ 
So I propose that at the beginning of each existing "component/module" documentation (for example, Kyma Metrics and Logs; or for Eventing, Using Kyma Eventing with SAP Event Mesh). we should simply link to the Admin/Ops topic that explains how to install a Kyma module (I assume/hope that the process is identical for all Kyma modules).
I don't know whether we have Kyma components/modules that don't have a Help Portal topic yet, but if those currently have no need for a separate topic, why would there be a need in the future?
Hi @NHingerl @majakurcius I Nina's summary/example from slack on how a module documentation could look and put it here: from Nina Hingerl: To illustrate what I mean, in practice that would mean the following, for example: If the module team wants to explain the basic idea of their module and present the an overview, they’d pick the concept template. For any step instructions, be it installing, configuring, any specific use cases, they’d pick the task template. (Edit: I hope installing the module works the same for all modules, so one common instructional doc should be sufficient, to which the module-specific documentation links as needed). If there’s any other explanatory document needed to go into more detail than the overview provided, they pick the concept template and slot the doc into the navigation structure wherever it makes most sense. If there’s more than one instruction needed (most likely yes), either sequentially or interspersed between other docs, they pick the task template again. If they want to provide an overview introducing a sequence of several docs, they pick the concept template. If there’s any typical troubleshooting, they pick the troubleshooting template and put it into the place where it fits best. Imo, this should cover 80-90% of the required documentation. For any other docs, we could see if they fit into the aforementioned templates after some rephrasing, or whether they need another template.
Here is a document that summarizes what we know so far. Feel free to add any suggestions or questions.
The current documentation tasks: Prepare customer-facing documentation for Serverless Manager (https://github.com/kyma-project/serverless-manager/issues/33) Prepare customer-facing documentation for Keda Manager (https://github.com/kyma-project/keda-manager/issues/80) Prepare documentation common for all the modules (https://github.com/kyma-project/kyma/issues/16421) Keda manager developer's guide (https://github.com/kyma-project/keda-manager/issues/84) Adjust the SKR documentation to the Modularization requirements (https://github.tools.sap/kyma/backlog/issues/3345)