PLIP: Plone 7 Documentation Layout, Structure, Theme, and Search to Improve Usability

[stevepiercy]

PLIP: Plone 7 Documentation Layout, Structure, Theme, and Search to Improve Usability

Responsible Persons

Proposer: Steve Piercy, @stevepiercy

Seconder: Víctor Fernández de Alba, @sneridagh

Abstract

This PLIP will improve the layout and structure for Plone 7 Documentation with an upgraded Plone Sphinx Theme. This will also improve its usability.

• Dependencies for Plone Sphinx Theme will be simplified.
• Plone 7 Documentation will have clearly targeted guides for Users, Developers, and Contributors.
• Plone 7 Documentation API reference guides will be collected into a single location.
• Content authors will use the Diátaxis Framework as a guide for well organized and structured content.
• Nuclia search will replace the default Sphinx search in Plone Sphinx Theme.

Motivation

Documentation of Plone across all of its versions has always had shortcomings. Plone 6 Documentation is no different, but the primary issues have been identified as motivating factors for change.

Usability issues

Plone Sphinx Theme is used as the theme when documenting Plone projects. It works well for sites that benefit from shallow navigation, such as Plone Training and Plone REST API, where all the subpages are in a single navigation sidebar. Plone 6 Documentation, however, outgrew this simple layout, due to its deeply nested content.

Compounding this problem, the ad-hoc structure of Plone 6 Documentation—where the primary navigation items are the major components of Plone, including Volto UI, Classic UI, REST API, and Backend—is a collection of meaningless terms to the first-time Plone visitor.

Additionally, content authors lacked familiarity with any documentation framework or guidelines for how to write documentation for a specific purpose. Often documentation would mix how-to guides with API reference and explanation of design decisions.

Lastly, the default search in Sphinx is suboptimal.

All of these usability issues together make it difficult for specific audiences to find the information they seek.

Dependency issues

Plone Sphinx Theme has two upstream dependencies, Sphinx Book Theme as the parent and PyData Sphinx Theme as the grandparent. Because of this dependency chain, development and feature adoption in Sphinx Book Theme lags behind PyData Sphinx Theme. Plone Sphinx Theme pins PyData Sphinx Theme to an earlier version due to a bug. This also results in Plone Sphinx Theme no longer receiving new features from PyData Sphinx Theme, such as improved accessibility and navigation. In another example of development lag, Plone Sphinx Theme had to wait for Sphinx Book Theme to support its toggle between light, dark, and system preference modes long after it was available in PyData Sphinx Theme.

The authors of Sphinx Book Theme have shifted their priorities to other projects. They lack the resources to make Sphinx Book Theme any more than a thin layer on top of PyData Sphinx Theme.

PyData Sphinx Theme is backed by a well-funded, sustainable 501(c)(3) nonprofit public charitable organization, NumFOCUS.

Based on the greater support for PyData Sphinx Theme, it makes sense to adopt PyData Sphinx Theme is the immediate parent of Plone Sphinx Theme.

Assumptions

PyData Sphinx Theme will continue to be supported and developed.

Proposal and Implementation

Version policy

Plone Sphinx Theme 2.0.0 will derive directly from PyData Sphinx Theme. Plone Sphinx Theme 1.x.x will continue to derive from Sphinx Book Theme, and may receive updates from the community, but it will not be actively maintained. Features will not be backported from 2.x.x to 1.x.x.

Layout

A new layout will be established, following the Theme Structure and Layout of PyData Sphinx Theme.

Header / Navigation Bar

From left to right, the logo region will contain the Plone logo, project title, and version switcher, if applicable. Section links will contain the guides described below, and additional links including a link to the source repository and other links to be determined. The search interface will go in the persistent components section, and buttons for toggling light, dark, and auto modes, and social media will go in the components section.

On small screens, the header contains collapsible primary sidebar navigation, logo, project name, search, and collapsible secondary sidebar navigation.

On all screens, an optional announcement banner may be displayed above the header.

Primary Sidebar

The Primary Sidebar will contain the navigation for the selected guide from the Header / Navigation Bar.

The guides will include User, Developer, API, and Contributor.

The current distinction made between Administrators, Developers, and Deployment in Plone 6 Documentation will be merged into a single Developer Guide. The Developer Guide will contain how-to guides that may be put into related topic groups.

API reference guides for plone.api, plone.restapi, @plone/registry, and Plone REST API JavaScript client will be represented in the Header / Navigation Bar as a single reference guide labeled API. The APIs be listed with their documentation topics in the Primary Sidebar when API is selected.

Article Header

The Article Header will contain navigation breadcrumbs. It may contain other information, if helpful.

Article Footer

The Article Footer will contain Next and Previous navigation buttons, and may contain custom templates.

Secondary Sidebar

The Secondary Sidebar will contain within-page heading links, and feature scroll-spy, where the currently viewed heading gets highlighted and expanded in the Secondary Sidebar. It may also contain links, search as Suggest Edit.

Footer Content

This section will contain nothing, but it may be used in the future.

Footer

This section will contain the copyright statement, Sphinx and theme versions, and other relevant content, such as an acknowledgment of Read the Docs which provides free pull request preview builds of documentation.

Diátaxis Framework

Content authors will use the Diátaxis Framework as a guide for well organized and structured content. Its guidance is not absolute and inflexible, and should be used to help authors focus their writing on the task at hand.

Search

Nuclia is a service that accepts structured data from Plone documentation, then uses artificial intelligence (AI) search and generative answers to return relevant search results and interactive question and answers to further refine results. It can be used across multiple Plone properties, including Training, YouTube, and plone.org.

A Google Summer of Code (GSoC) project in 2023, Integrating Nuclia Widget resulted in a functional and improved search experience, but has stalled over styling issues with Sphinx Book Theme. With the removal of Sphinx Book Theme as a dependency, styling should become simpler, and integration with Plone Sphinx Theme can progress. You can view a demo of the GSoC project.

The search results will have no Primary or Secondary Sidebar.

Deliverables

• Announce removal of sphinx-book-theme from plone-sphinx-theme in plone-sphinx-theme documentation and the Community Forum.
• Make a final release of plone-sphinx-theme v1.x.x, with appropriate pins to the upstream sphinx-book-theme and pydata-sphinx-theme.
• Make a release of plone-sphinx-theme 2.0.0 with pydata-sphinx-theme as the direct parent theme.
• Create a branch in plone/documentation named 7 for development of Plone 7 Documentation. This is already done.
• Enable pull request previews. This is already done, but needs to be tested.
• Complete the integration and documentation of Nuclia Search in Plone Sphinx Theme.
• Write, organize, and curate documentation, using the Diátaxis Framework as a guide.
• Create automatic deployment of Plone 7 Documentation. @plone/ai-team

Risks

There is only one maintainer of Plone Sphinx Theme. The fallback is the Plone Foundation.

Redirects from docs.plone.org to various versions of Plone documentation are not publicly documented. It is unclear what would break without their publication.

Nuclia is donating its service to the Plone Foundation. If Nuclia rescinds its donation, or goes out of business, then the default Sphinx search would be restored.

These risks are minimal and acceptable, but it would be good to improve both situations.

Participants

• Steve Piercy, @stevepiercy
• @plone/documentation-team
• @plone/ai-team

[sneridagh]

@stevepiercy let's not forget about the docs that we have also for @plone/* packages. As they qualify as "API-first" packages, I guess we can put them in the API section.

[stevepiercy]

@sneridagh let's get specific and sufficiently detailed to take action. Out of all the packages listed in https://github.com/plone/volto/blob/main/PACKAGES.md, which have documentation that needs to be pulled in?

[sneridagh]

@stevepiercy no, for now only @plone/registry.

@plone/client have them integrated in Volto, right? Maybe it would be time for it to have a new home.

However, I can imagine to have (even a small single document) for each one of them.

Oh! Let's not forget about the Storybooks.

@plone/components have one
@plone/cmsui will have one
Seven will have one

[stevepiercy]

@sneridagh I added @plone/registry to the APIs.

@plone/client is currently a symlinked item at https://6.docs.plone.org/volto/client/index.html. It might be a good topic under APIs. Maybe you can think of a better home?

Storybooks are interesting critters. They are both demos and reference documentation. One option is to do something similar to what I did for Plone Training, where each Storybook has a landing page in documentation that can then be viewed. They could be under the More menu as in PyData Sphinx Theme. Currently we bury it under Contributing to Volto > Documentation > Storybook entry.