Documentation Office Hours - Aug 25, 2023

Community
,
1

2023-08-25T03:00:00Z

2023-08-25 (Asia)

Attendees

  • Mark Waite
  • Kris Stern
  • Meg McRoberts

Agenda

  • Google Summer of Code
    • Tutorial improvements from Ashutosh Docker compose project
      • Needs one or more new docker repositories and docker containers in those repositories
        • Infra team can’t do those docker repositories currently
      • Could create a prototype that uses Ashutosh’s or Bruno’s personal containers for now
        • Not publish to the official site
      • Allows test drive of workflow and test drive of new versions
    • New site layout (demonstration recorded in UX SIG and in today’s Docs Office Hours (EU)) - extended 4 weeks
      • Gatsby integration being refined, considering using strapi as the backend data store
      • Strapi has an admin dashboard but Kris wants to retain the current flow for processing blog posts
        • Strapi allows reviews but it would be very different
        • Can make it publicly visible, but takes some work
          • Make everyone a reader, but review comments not allowed by readers
          • Reviews submitted through the portal or dashboard
          • Preserving the existing process will require additional work
        • Review process would not use GitHub pull requests
        • Just for blog posts
      • Antora and GitHub pull requests for review
        • Some non-versioned documentation
        • All versioned documentation
      • Lots of work in the transition to the new workflow and new tooling
        • Will need discussion and lots more work
      • Vandit has created very nice looking documentation with Antora
        • Versions managed as individual branches
    • GitLab Plugin Modernization
      • Should we invite Harsh to be one of the maintainers of the plugin?
        • Mark supports that idea
    • Plugin Health Score (extended ~3 weeks)
  • How to describe the process of choosing a plugin bill of materials version
    • Described in issue 2359
    • Consider using updatecli to update the version string explicitly
    • Consider including static references to older versions in addition to the most recent release
    • Consider adding a blog post that highlights how to do it
  • Adding existing requirements/support policy documentation to System Administration section (new chapter/sections)
    • Diagnosing Kevin’s prototype - debug session
    • Currently, support policy docs are linked in the installation guides and are searchable, but not necessarily in a section in the navigation.
    • Similarly for the Java requirements & Java upgrade docs
    • Support policy could function like “Reverse proxy configurations” with collapsible navigation
    • Meg suggested “Platform Information” as a name for the section, Kris agrees that’s a good name for the section
    • After installing, it is less likely that users would return to the installation docs
      • At this point, I have gotten the pages/book/chapter working in a local clone, redirects for the existing links/docs, and things seem to be working properly for the most part.
      • Still need to get index page working, and making sure that it is shown on the navigation/overview
      • Pushed changes to my jenkins.io repo, trying to determine what is causing the issue.
  • Vale.sh - command line evaluation of prose
    • Mentioned by Gavin Mogan that he’s using at his office
    • Mentioned by Darin Pope as interesting as well
  • DevOps World Tour web site
    • Sep 13-14 - New York - Mark is speaking
    • Sep 27 - Chicago - Mark is speaking
    • Oct 18-19 - Santa Clara - Mark is speaking
    • Oct 26 - Singapore Olivier Lamy is speaking
    • Nov 29 - London Tim Jacomb is speaking