List view
Project page: https://github.com/keptn/community/tree/main/mentorship/gsoc/2022/projects/new-docs-site-engine
Overdue by 2 year(s)•Due by September 12, 2022We need a good "Intro to Keptn" or "What is Keptn" or "Keptn Overview" document at the top of the doc set. Much of the material currently in the "Concepts" articles can be repurposed into this section, but we need a more narrative presentation of the material than we currently have. We may want to create an expanded "Architecture" document as part of this same effort. Many of the "Concepts" articles contain a good description about how that feature or component actually works and it may be that creating an "Intro" doc that does not go quite so deep would be more effective, with an expanded "Architecture" document available with the more detailed information about how things work and fit together. 19 May update: Adam Gartner is interested in this so I am working with him. He has a narrative "in his head" and that material may drive this project, then we will merge what he has with the "Concepts" material, etc, that we currently have and build this out. Meha Bhalodiya is interested in doing some writing here as well. Having the three of us collaborate on this should result in some very nice doc!
No due date•2/2 issues closedWe currently have a Reference section under each project release, which includes: * Reference pages for all Keptn CLI commands, generated automatically We also have: * Reference pages for the Keptn API, although the docs only include instructions for viewing these on ones Keptn installation. These pages should be viewable from the documentation as well. We need: * Reference pages for all Keptn files that users and/or developers access * Miscellaneous pages for material that doesn't fit elsewhere, such as a page that lists the environment variables that control how the distributor works The reference section should be pulled out of the release-specific sections since each page can contain a "Differences between versions" section that identifies differences. See https://docs.google.com/document/d/1rmSGUFsnYuNc_BGHGmkW-9iB3hrOYbMeA-mJmMOjGRk/edit#heading=h.jwrhldzbo0x6 for the full proposal.
No due date•9/9 issues closedOur current set of tutorials (plus the Quick Start and some Getting Started guides) require significant work to bring them up to date and to make them useful for customers. Issues include: * Current tutorials are for Keptn 0.11.x * Current tutorials use the sockshop app which is not supported after Keptn 0.13.x * The podtato-head app may be what we use going forward but it is apparently not ready to be used. Specifically, questions as to whether it provides an "artificial slowdown" mode as required to do the quality gates evaluation for performance. General quality issues for tutorials include: * The installation steps required at the beginning are onerous and may discourage people from going through the full tutorial to be impressed by Keptn's capabilities. * The text needs more context and explanation about what is being done and why so the user begins to understand key Keptn practices and capabilities Structural issues to revisit: * Would using Katacoda or Killercoda for these tutorials improve the user experience and perhaps reduce the maintenance burden for these tutorials? * Can we automate testing the steps taken to run the exercises so they can be easily checked against new Keptn releases? * If we do not use Katacoda/Killercoda, do we want to continue using the keptn/tutorials repo for tutorial source or move the source into the keptn.github.io repo? * As we add integrations for more data/observability platforms, do we continue to produce separate tutorials for each new platform or could we create generic tutorials for the introductory pieces that, while using a specific data/observability platform integration, would be sufficient for users of all observability platforms? * How do we want to organize the ownership of the tutorials in combination with their dependencies? * Do we continue to share resources for all tutorials in keptn/examples? If so, how do we avoid conflicts where modifications are made to these resources for one tutorial but perhaps break other tutorials? See also https://github.com/keptn/tutorials/issues/206 .
No due date•1/1 issues closedThe installation documentation in the current doc set is mostly provided in the <0.xx.x>/operate section and has the following issues: * Information is spread over many files in many locations with no summary list to show users what to do in what order * Significant duplication of content which is difficult to maintain and has led to some inconsistencies and conflicts * Some tutorials have better information about some steps than the installation docs The proposal is to create a separate section entitled “Install Keptn” that is comprehensive and, as much as possible, removes duplicate installation information from all other docs with the following characteristics: * Each major task will have its own subsection with appropriate subsections in each. * The top file in each section/subsection will include an annotated list of the topics in the subsections and other high-level information that is appropriate. For example: * The section on installing a k8s cluster will briefly discuss the options that are particularly suited for self-study, demos, and development environments. * The section on installing Keptn explains that this can be done manually, using the kindkeptn docker image, or using the helm chart, with each option linking to the subsection that provides details. * When possible and appropriate, sections will either embed or link to relevant videos that show details of the steps required. Videos and text should match; it is particularly useful if commands issued in the video are included in the text so they can be copy/pasted. See https://docs.google.com/document/d/1fQaLxsnIRjHfqzZl-D2vJ8VoeYpaSEdg0CIH9IbmxyU/edit#heading=h.gd4zlpbq2hxt for a detailed outline.
No due date•9/9 issues closedWe have many tutorials, a Quick Start guide, et cetera, all of which give a "remedial" introduction to Keptn and what it can do. These have myriad problems, including: * Cumbersome upfront installation procedures that delay getting to the actual Keptn material * Inadequate explanation and context * Are running on very old versions of Keptn * Use the sockshop app, which cannot be run on Keptn versions later than 0.13.x We will replace all of these beginning documents with a single tutorial that uses KataCoda or kilrcoda (an open source version of KataCoda) to quickly and easily install/set up the latest version of Keptn, then do a few exercises based on the podtato-head application. At this level, it is not necessary to have separate tutorials for different data sources and such. This work will be backed up with other doc work to provide better information for people who are getting started with Keptn. One of our current problems is that the only "getting started" materials is the tutorials. We need a set of "Creating a project" docs, with an intro that outlines the basic steps used for all projects then individual docs for "Create full multi-stage delivery project", "Create test and evaluation project", "Create an evaluation only project", "Create a delivery project", "Create an auto-remediation project", and so forth. Each of these will provide details and guidelines for the steps that are required, with some steps linking to other files for details plus some detailed example shipyard files, etc. Acceptance criteria: - A new tutorial is available through kilrcoda, using the most recent Keptn version (0.15.x?) and the podtato-head application and covering at least the exercises in the old "Full Tour" tutorials. - The tutorial is manually tested - The tutorial is optimized for user experience and provides enough context to increase the user's understanding of Keptn 19 May 2022 update: Christian Kreuzberger and Adam Gardner have exercises working that use podtato-head and can do everything that the sockshop applications could do. Afzal is working on getting a tutorial working on kilrcoda that uses podtato-head so we can evaluate the PoC and then decide what we want to do. Kilrcoda is much cheaper to run that Kadacoda but both do have a hosting cost, etc for which we need budget to go forward. 23 May 2022 note: We had a good GSoC proposal to implement Katacoda for tutorials and are considering moving forward with that as an LFX project.
Overdue by 2 year(s)•Due by August 1, 2022•14/14 issues closed