|
| 1 | +--- |
| 2 | +title: Docsy priorities for 2024 |
| 3 | +linkTitle: 2024 Priorities |
| 4 | +author: > |
| 5 | + [Patrice Chalin](https://github.com/chalin) ([CNCF](https://www.cncf.io/)), |
| 6 | + for the [Docsy Steering |
| 7 | + Committee](https://www.docsy.dev/blog/2022/hello/#introducing-the-psc) |
| 8 | +date: 2023-11-28 |
| 9 | +# prettier-ignore |
| 10 | +cSpell:ignore: CNCF Chalin opentelemetry namespacing docsy customizability deprioritize |
| 11 | +--- |
| 12 | + |
| 13 | +> **TL;DR** 1.4K projects use Docsy! The top user-project focused priorities for |
| 14 | +> 2024 are: improving Docsy's stability, usability & customizability, and |
| 15 | +> cohesiveness while performing feature consolidation. |
| 16 | +
|
| 17 | +## Docsy is a popular theme |
| 18 | + |
| 19 | +The Hugo-Docsy tool combo is powerful and effective, as I've [blogged about |
| 20 | +elsewhere]. It's maybe no surprise then, to see Docsy [used by 1.4K |
| 21 | +projects][docsy-analytics][^0]. Why is Docsy popular? I can't say for sure, but |
| 22 | +I use and recommend Docsy because it has the core features --- necessary for |
| 23 | +publishing non-trivial tech-doc sites --- that projects seem to want and need, |
| 24 | +including support for versioning, multiple languages, auto-generated site |
| 25 | +navigation, and more. It's quick to set up, and it allows projects to focus on |
| 26 | +delivering site content rather than writing site template code. |
| 27 | + |
| 28 | +## User-project focused and long-term vision |
| 29 | + |
| 30 | +[Steering committee][sc] members, including myself, are actively supporting |
| 31 | +several projects at the CNCF and Google that rely on Docsy. Both as users and |
| 32 | +contributors to Docsy, we share a vested interest in ensuring Docsy's long-term |
| 33 | +health. Our envisioned priorities for Docsy are: |
| 34 | + |
| 35 | +1. **Stability** of Docsy's **core** through bug fixes and necessary upgrades |
| 36 | + --- the [migration from the end-of-life Bootstrap 4 to version |
| 37 | + 5][bs5-migration] is one example of such an effort. |
| 38 | +2. Reducing **technical debt**. |
| 39 | +3. **Improving usability, customizability, and maintainability** by, in |
| 40 | + particular, working to more **clearly separate** and document "**API |
| 41 | + surfaces**" --- or configuration / customization surfaces. |
| 42 | +4. **Feature consolidation**, which I will explain next. |
| 43 | + |
| 44 | +Google open sourced Docsy a little over five years ago, and thanks to community |
| 45 | +contributions, it has grown in stability and its feature set. During that time, |
| 46 | +Docsy also accumulated considerable technical debt, and it now suffers (IMHO) |
| 47 | +from a mild case of software bloat/feature creep. So, in addition to investing |
| 48 | +in Docsy's long-term stability and maintainability, we need to **reaffirm |
| 49 | +Docsy's core features** and deprioritize the rest[^1] --- lest we suffer a [fate |
| 50 | +similar to projects like `cross-env`][ce]. Consider Docsy on a feature diet. |
| 51 | + |
| 52 | +Before tackling 2024 objectives, we plan on setting up a **test infrastructure** |
| 53 | +with (a growing) suite of tests to help us ensure Docsy's integrity as it |
| 54 | +evolves. |
| 55 | + |
| 56 | +## Conclusion |
| 57 | + |
| 58 | +This is a tall order for 2024 and beyond, but I believe that slow and steady |
| 59 | +wins the day. |
| 60 | + |
| 61 | +We're eager to hear from you, the Docsy community! [Share your thoughts] on our |
| 62 | +focus areas and how we can enhance Docsy. Take a look at our issue triage into |
| 63 | +[quarterly milestones] for a rough idea of what is targeted for upcoming |
| 64 | +releases. Vote for or comment on issues that are important to you, and we'll do |
| 65 | +our best to respond and adjust release targets within the boundaries of our set |
| 66 | +priorities. Better yet, volunteer to work on the current quarter's tasks. As we |
| 67 | +start the new year, we'll be especially interested in getting help with testing |
| 68 | +and feature consolidation. |
| 69 | + |
| 70 | +[^0]: According to [Docsy's GitHub analytics][docsy-analytics]. |
| 71 | +[^1]: |
| 72 | + Features outside the identified core could even be moved to a separate |
| 73 | + community-maintained repo. The steering committee is also considering a |
| 74 | + "plugin" architecture for some secondary features, such as (to mention just |
| 75 | + one) Mermaid support. |
| 76 | + |
| 77 | +[blogged about elsewhere]: |
| 78 | + https://www.cncf.io/blog/2023/01/19/fast-and-effective-tools-for-cncf-and-open-source-project-websites/ |
| 79 | +[docsy-analytics]: https://github.com/google/docsy/network/dependents |
| 80 | +[ce]: https://github.com/kentcdodds/cross-env/issues/257 |
| 81 | +[sc]: https://www.docsy.dev/blog/2022/hello/#introducing-the-psc |
| 82 | +[bs5-migration]: https://www.docsy.dev/blog/2023/bootstrap-5-migration/ |
| 83 | +[share your thoughts]: https://github.com/google/docsy/discussions |
| 84 | +[quarterly milestones]: https://github.com/google/docsy/milestones |
0 commit comments