From 4e428e7f7e75237f6ff74fc1cf72686735af401b Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Mon, 27 Nov 2023 11:17:58 -0500 Subject: [PATCH 1/3] [blog] Docsy priorities for 2024 --- .../en/blog/2023/bootstrap-5-migration.md | 4 +- userguide/content/en/blog/2023/docsy-0.7.md | 4 +- .../en/blog/2023/priorities-for-2024.md | 84 +++++++++++++++++++ 3 files changed, 88 insertions(+), 4 deletions(-) create mode 100644 userguide/content/en/blog/2023/priorities-for-2024.md diff --git a/userguide/content/en/blog/2023/bootstrap-5-migration.md b/userguide/content/en/blog/2023/bootstrap-5-migration.md index 234cf9f2c8..c7a5ddfe02 100644 --- a/userguide/content/en/blog/2023/bootstrap-5-migration.md +++ b/userguide/content/en/blog/2023/bootstrap-5-migration.md @@ -5,8 +5,8 @@ description: > An experience report in migrating Docsy from Bootstrap 4 to 5.2, with insights and instructions. author: > - [Patrice Chalin](https://github.com/chalin), [CNCF](https://www.cncf.io/) & - Docsy Steering Committee + [Patrice Chalin](https://github.com/chalin) ([CNCF](https://www.cncf.io/) & + [Docsy Steering Committee](https://www.docsy.dev/blog/2022/hello/#introducing-the-psc)) date: 2023-06-05 canonical_url: https://www.cncf.io/blog/2023/06/05/migrating-docsy-to-bootstrap-5/ cSpell:ignore: CNCF Chalin opentelemetry techdocs diff --git a/userguide/content/en/blog/2023/docsy-0.7.md b/userguide/content/en/blog/2023/docsy-0.7.md index 6c53bbec0a..ea131b5bb4 100644 --- a/userguide/content/en/blog/2023/docsy-0.7.md +++ b/userguide/content/en/blog/2023/docsy-0.7.md @@ -3,8 +3,8 @@ title: Upgrading to Docsy 0.7 & Bootstrap 5 linkTitle: Upgrading to Docsy 0.7 description: A guide to upgrading to Docsy 0.7 and Bootstrap 5 with examples author: > - [Patrice Chalin](https://github.com/chalin), [CNCF](https://www.cncf.io/) & - Docsy Steering Committee + [Patrice Chalin](https://github.com/chalin) ([CNCF](https://www.cncf.io/) & + [Docsy Steering Committee](https://www.docsy.dev/blog/2022/hello/#introducing-the-psc)) date: 2023-08-03 cSpell:ignore: CNCF Chalin opentelemetry namespacing docsy --- diff --git a/userguide/content/en/blog/2023/priorities-for-2024.md b/userguide/content/en/blog/2023/priorities-for-2024.md new file mode 100644 index 0000000000..d790058e18 --- /dev/null +++ b/userguide/content/en/blog/2023/priorities-for-2024.md @@ -0,0 +1,84 @@ +--- +title: Docsy priorities for 2024 +linkTitle: 2024 Priorities +author: > + [Patrice Chalin](https://github.com/chalin) ([CNCF](https://www.cncf.io/)), + for the [Docsy Steering + Committee](https://www.docsy.dev/blog/2022/hello/#introducing-the-psc) +date: 2023-11-27 +# prettier-ignore +cSpell:ignore: CNCF Chalin opentelemetry namespacing docsy customizability deprioritize +--- + +> **TL;DR** 1.4K projects use Docsy! The top user-project focused priorities for +> 2024 are: improving Docsy's stability, usability & customizability, and +> cohesiveness while performing feature consolidation. + +## Docsy is a popular theme + +The Hugo-Docsy tool combo is powerful and effective, as I've [blogged about +elsewhere]. It's maybe no surprise then, to see Docsy [used by 1.4K +projects][docsy-analytics][^0]. Why is Docsy popular? I can't say for sure, but +I use and recommend Docsy because it has the core features --- necessary for +publishing non-trivial tech-doc sites --- that projects seem to want and need, +including support for versioning, multiple languages, auto-generated site +navigation, and more. It's quick to set up, and it allows projects to focus on +delivering site content rather than writing site template code. + +## User-project focused and long-term vision + +[Steering committee][sc] members, including myself, are actively supporting +several projects at the CNCF and Google that rely on Docsy. Both as users and +contributors to Docsy, we share a vested interest in ensuring Docsy's long-term +health. Our envisioned priorities for Docsy are: + +1. **Stability** of Docsy's **core** through bug fixes and necessary upgrades + --- the [migration from the end-of-life Bootstrap 4 to version + 5][bs5-migration] is one example of such an effort. +2. Reducing **technical debt** +3. **Improving usability, customizability, and maintainability** by, in + particular, working to more **clearly separate** and document "**API + surfaces**" --- or configuration / customization surfaces. +4. **Feature consolidation**, which I will explain next. + +Google open sourced Docsy a little over five years ago, and thanks to community +contributions, it has grown in stability and its feature set. During that time, +Docsy also accumulated considerable technical debt, and it now suffers (IMHO) +from a mild case of software bloat/feature creep. So, in addition to investing +in Docsy's long-term stability and maintainability, we need to **reaffirm +Docsy's core features** and deprioritize the rest[^1] --- lest we suffer a [fate +similar to projects like `cross-env`][ce] Consider Docsy on a feature diet. + +Before tackling 2024 objectives, we plan on setting up a **test infrastructure** +with (a growing) suite of tests to help us ensure Docsy's integrity as it +evolves. + +## Conclusion + +This is a tall order for 2024 and beyond, but I believe that slow and steady +wins the day. + +We're eager to hear from you, the Docsy community! [Share your thoughts] on our +focus areas and how we can enhance Docsy. Take a look at our issue triage into +[quarterly milestones] for a rough idea of what is targeted for upcoming +releases. Vote for or comment on issues that are important to you, and we'll do +our best to respond and adjust release targets within the boundaries of our set +priorities. Better yet, volunteer to work on the current quarter's tasks. As we +start the new year, we'll be especially interested in getting help with testing +and feature consolidation. + +[^0]: According to [Docsy's GitHub analytics][docsy-analytics]. +[^1]: + Features outside the identified core could even be moved to a separate + community-maintained repo. The steering committee is also considering a + "plugin" architecture for some secondary features, such as (to mention just + one) Mermaid support. + +[blogged about elsewhere]: + https://www.cncf.io/blog/2023/01/19/fast-and-effective-tools-for-cncf-and-open-source-project-websites/ +[docsy-analytics]: https://github.com/google/docsy/network/dependents +[ce]: https://github.com/kentcdodds/cross-env/issues/257 +[sc]: https://www.docsy.dev/blog/2022/hello/#introducing-the-psc +[bs5-migration]: https://www.docsy.dev/blog/2023/bootstrap-5-migration/ +[share your thoughts]: https://github.com/google/docsy/discussions +[quarterly milestones]: https://github.com/google/docsy/milestones From 6d542bc04ec21e41f1febd97b62b755eeac2deac Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Mon, 27 Nov 2023 14:39:08 -0500 Subject: [PATCH 2/3] Fix punctuation --- userguide/content/en/blog/2023/priorities-for-2024.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/userguide/content/en/blog/2023/priorities-for-2024.md b/userguide/content/en/blog/2023/priorities-for-2024.md index d790058e18..25cab72633 100644 --- a/userguide/content/en/blog/2023/priorities-for-2024.md +++ b/userguide/content/en/blog/2023/priorities-for-2024.md @@ -35,7 +35,7 @@ health. Our envisioned priorities for Docsy are: 1. **Stability** of Docsy's **core** through bug fixes and necessary upgrades --- the [migration from the end-of-life Bootstrap 4 to version 5][bs5-migration] is one example of such an effort. -2. Reducing **technical debt** +2. Reducing **technical debt**. 3. **Improving usability, customizability, and maintainability** by, in particular, working to more **clearly separate** and document "**API surfaces**" --- or configuration / customization surfaces. @@ -47,7 +47,7 @@ Docsy also accumulated considerable technical debt, and it now suffers (IMHO) from a mild case of software bloat/feature creep. So, in addition to investing in Docsy's long-term stability and maintainability, we need to **reaffirm Docsy's core features** and deprioritize the rest[^1] --- lest we suffer a [fate -similar to projects like `cross-env`][ce] Consider Docsy on a feature diet. +similar to projects like `cross-env`][ce]. Consider Docsy on a feature diet. Before tackling 2024 objectives, we plan on setting up a **test infrastructure** with (a growing) suite of tests to help us ensure Docsy's integrity as it From af46fc5dd9af927b4b1006275cadc44752a7c310 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Mon, 27 Nov 2023 14:40:00 -0500 Subject: [PATCH 3/3] Keep original 11/28 target date --- userguide/content/en/blog/2023/priorities-for-2024.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/userguide/content/en/blog/2023/priorities-for-2024.md b/userguide/content/en/blog/2023/priorities-for-2024.md index 25cab72633..b18a18e59d 100644 --- a/userguide/content/en/blog/2023/priorities-for-2024.md +++ b/userguide/content/en/blog/2023/priorities-for-2024.md @@ -5,7 +5,7 @@ author: > [Patrice Chalin](https://github.com/chalin) ([CNCF](https://www.cncf.io/)), for the [Docsy Steering Committee](https://www.docsy.dev/blog/2022/hello/#introducing-the-psc) -date: 2023-11-27 +date: 2023-11-28 # prettier-ignore cSpell:ignore: CNCF Chalin opentelemetry namespacing docsy customizability deprioritize ---