Purge empty pages and todos

[stevepiercy]

We've had empty pages and TODOs for over three years in Plone 6 Documentation, especially under the Backend section, but also under Deployment, Classic UI, Volto, and Contributing. The Plone 6.1 milestone has only 17% of its issues completed after the release of Plone 6.1. The lack of current and accurate documentation for Plone 6 is the single greatest barrier to entry for all audiences. This reflects extremely poorly upon Plone, where documentation is perceived as less than an afterthought.

The following list of URLs are affected.

Purge empty pages. A page is empty when either it has no content or its only content is a TODO. If there is no existing issue for the page, then create a new issue.

All other pages in the list have content with at least one TODO. For these pages, preserve the TODO. If the TODO does not contain a link to an existing issue, then create a new issue and add its URL to the TODO, except for obsolete TODOs, such as Upgrading Plone 4.x to 5.0.

Configure conf.py to hide the display of TODOs, changing code from the following...

documentation/docs/conf.py

Lines 381 to 385 in b4462a8

	# -- Options for sphinx.ext.todo -----------------------
	# See http://sphinx-doc.org/ext/todo.html#confval-todo_include_todos
	todo_include_todos = True

...to the following.

# -- Options for sphinx.ext.todo -----------------------

# See http://sphinx-doc.org/ext/todo.html#confval-todo_include_todos
todo_include_todos = False
todo_emit_warnings = True
todo_link_only = True

Ref: https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#configuration

• https://6.docs.plone.org/backend/annotations.html
• https://6.docs.plone.org/backend/behaviors.html#built-in-behaviors below the table. TODO: Linked issue is complete.
• https://6.docs.plone.org/backend/configuration-registry.html
• https://6.docs.plone.org/backend/control-panels.html - Adds docs for creating custom control panel #1909
• https://6.docs.plone.org/backend/portal-actions.html#expressions TODO
• https://6.docs.plone.org/backend/search.html TODO and empty headings
• https://6.docs.plone.org/backend/security.html
• https://6.docs.plone.org/backend/sending-email.html
• https://6.docs.plone.org/backend/subscribers.html - Migrate Subscribers (event handlers) #1918
• https://6.docs.plone.org/backend/traversal-acquisition.html
• https://6.docs.plone.org/backend/upgrading/preparations.html#back-up-your-plone-site TODO - Migrate backing up Plone docs #1919
• https://6.docs.plone.org/backend/upgrading/troubleshooting.html TODO
• https://6.docs.plone.org/backend/upgrading/version-specific-migration/p4x-to-p5x-upgrade.html TODO
• https://6.docs.plone.org/backend/users-groups.html
• https://6.docs.plone.org/backend/vocabularies.html
• https://6.docs.plone.org/backend/workflows.html
• https://6.docs.plone.org/backend/zodb.html - ZODB chapter #1894
• https://6.docs.plone.org/classic-ui/forms.html multiple TODOs
• https://6.docs.plone.org/classic-ui/templates.html
• https://6.docs.plone.org/classic-ui/viewlets.html multiple TODOs
• https://6.docs.plone.org/classic-ui/views.html multiple TODOs
• https://6.docs.plone.org/conceptual-guides/components.html TODO
• https://6.docs.plone.org/conceptual-guides/package-management.html#manage-frontend-node-js-packages TODO
• https://6.docs.plone.org/contributing/core/plip-review.html#javascript TODO
• https://6.docs.plone.org/contributing/documentation/themes-and-extensions.html and purge the extension from conf.py and possible PST.
• https://6.docs.plone.org/deployment/caching/rulesets-and-caching-operations.html#no-caching-plone-app-caching-nocaching TODO
• https://6.docs.plone.org/deployment/continuous-integration-and-deployment.html
• https://6.docs.plone.org/deployment/index.html TODO
• https://6.docs.plone.org/deployment/optimize-and-tune.html
• https://6.docs.plone.org/deployment/orchestration.html
• https://6.docs.plone.org/i18n-l10n/language-negotiation.html TODOs should be a warning.
• https://6.docs.plone.org/i18n-l10n/translating-content.html#language-selector TODO
• https://6.docs.plone.org/i18n-l10n/translating-text-strings.html TODO should be a warning.
• https://6.docs.plone.org/plone.restapi/docs/source/usage/content.html multiple TODOs
• https://6.docs.plone.org/volto/client/actions/database.html
• https://6.docs.plone.org/volto/conceptual-guides/index.html add toctree
• https://6.docs.plone.org/volto/contributing/react.html
• https://6.docs.plone.org/volto/contributing/routing.html
• https://6.docs.plone.org/volto/user-manual/blocks.html multiple TODOs
• https://6.docs.plone.org/volto/user-manual/index.html

@plone/volto-team @plone/restapi-team @plone/ci-team @plone/classicui-team @plone/marketing-communications @plone/documentation-team @plone/developers

[sneridagh]

+1

[gforcada]

Just giving my 2 cents...

What would be the purpose of removing the TODOs? 🤔 we are doing pretty bad at documenting the existing functionality, but removing the TODOs would only hide that there is such a thing as annotations, etc... or?

In another issue it was mentioned that as documentation for one or another reason has not been ported/written, that we could point to community.plone.org. As diataxis recommends: one step at a time.

Specially on the backend/Classic UI part, we are slow, neglecting if you want, but things are pretty stable and there are no hundreds of newcomers coming to us. That mostly applies to the cool kid in the project (volto 😄 ).

I can understand the frustration, but I'm not sure that removing TODOs is giving us a better documentation. At least we say that there is something that should be there 🤷🏾

[acsr]

After listening to @gforcada I remember that in Sphinx there are TODOs that are only rendered if the option is activated and can be listed on a special page. I am not sure if these current MyST based todo admonitions are visible in the official docs.

Therefore we should keep invisible markup and allow to exclude unfinished stuff from the public docs, and on the other hand make actual inline todos more obvious to our volunteers. Not finished with my opinion, but wanted to put this on record.

Maybe we need to display the in PITA in the right a*s but not in the public for beginners.

And keep in mind PITA is a kind of stimulation. I fully agree with @stevepiercy that the intensity needed a shift.

[Rotonen]

I agree with Gil: headline level end user discoverability of whatever Plone has wins here over it looking prettier.

Documentation sprint: where, when?

[sneridagh]

When a TODO is in place for half a decade, then the whole purpose of the placeholder loose all meaning. Of course this fact means different for each person reading this. However, at the end, communication is paramount, and this neglection transmit abandon and lack of care from the community maintaining it.

For me, to be honest, only causes one type of feeling which I will only tell you in person when you attend to any of the upcoming Plone Sprints this year.

We, as a community, often forget that we are not only documenting for ourselves, but for newbies and decision makers that wants to approach Plone. People that have no clue whatsoever of what an annotation is or what does it refers to.

@stevepiercy As stated before, you have my ack, let's remove all Plone Volto TODO list.

[acsr]

@sneridagh I feel with you both, but removing TODOs is not a solution, just a kind of desperate revenge. Take a look at the open issues in plone/volto by numbers. I had similar experiences in the past. The only remaining challenge and reasonable reaction is to change what is missing by priority. I learned so much from writing documentation for Plone in the past. I like to volunteer in this topic. What we miss from my viewpoint is better onboarding.

I see the enormous efforts @stevepiercy is putting into the tasks and the frustration that may arise. But what are 3 years compared to the lifecycle of Plone?

In 2007 I was in the Plone 3 theming spint/class whatever by Denis Mishunov. I did not get a clue out of it but writing the stuff down and up in public boosted my community and Plone experience.

Last year I promised to give back what I learn from the current docs and improve what I am missing. It took over a year to start and jump in. Due to lacking docs… But I speed up…

Cake design by Sven @svx

In 2014 the Stroopwafel Sprint was a great effort to streamline the existing mess. I remember the confusion when we started, and the result. Therefore we may need a pure docs sprint again.

In 2019 we fixed the existing Algolia docs search mess with some other volunteers. The experience is not back for now after it broke. I am still waiting for Nuclia.

I truely agree that a call to action is missing. But guys no time for crybabies… A todo stays a todo and is not news. Hiding it is a pyrrhic victory. Not fixing them stays a shame too… Lets go for it.

We discussed today some AI approaches. I cannot promise to come with a prototype for such a workflow asap. But we can do some improvements soon or later. To be honest: Sometimes light is better visible in the darkness.