Purge empty pages and todos #1882
Comments
|
+1 |
|
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 🤷🏾 |
|
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. |
|
I agree with Gil: headline level end user discoverability of whatever Plone has wins here over it looking prettier. Documentation sprint: where, when? |
|
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. |
|
@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. |
|
That is a peeping briliant idea @acsr . If we can learn an decent generic llm to look/ingest the old docs and the current source code of plone 6.-, we can ask it to create updated minimal chapters on the missing Todo’s for backend and classic ui. And I happen to have a workstation class mac with 32gb idling at the moment. Installed Ollama on it, but didn’t have a subject to explore. Until now. |
|
In general I’m in favour of removing the current Todo’s from the docs. We don’t need to project manage this in the document itself. I will create a separate issue from the list above, where I’ll create subtasks. And we can add the issue to the plone 6.2 release project board. Then it gets also in the radar on the devs when the plips for the next release are discussed in the teams. Documentation for 6.2 was a separate card added on the plip brainstorm session board that we filled in at the Alpine City sprint. |
|
The original purpose of empty pages as placeholders and todos with links to open issues was to encourage contributions. After three years, the vast majority of them are still empty pages and unresolved todos and issues. Clearly they were not effective in achieving that goal. When something doesn't work as intended, you should stop doing it. @gforcada I hope that answers your question. We'll still have open issues to keep track of these things. It is my intent to toggle the public display of todos in the Sphinx configuration. Sorry, I wasn't clear about that originally. That way they can be easily searched in the source of documentation files and reference existing issues. An issue in a tracker and a todo in the documentation source files should reference each other. Our community has a lack of motivated content experts to write down at least some technical notes that we can turn into documentation, and have notes peer reviewed for technical accuracy. This is possibly because the community started in 2001 and most of the knowledgeable folks have died, retired, or moved on to more rewarding things. Looking from the outside, I think placeholders and todos in public documentation are a poor reflection on the product, leading to the perception that documentation is less than an afterthought. That can have a negative impact on the adoption of the product by developers, users, and organizations. As far as AI, see the separate discussion in #1887. Please let's not hijack this issue with discussion of that topic. @Rotonen I participate in every sprint, conference, and monthly Plone Tune-up Day remotely, if not in person. I beg people to write in their native language if they're not comfortable with English, to write technical notes that I can wordsmith in to narrative documentation, or to peer review technical things where I have zero knowledge (which is most of Plone for me). In other words, remove barriers to entry and make it easy to contribute to docs. Although there have been a few brilliant contributions for which I am grateful (you know who you are 😉 ❤ ), it has been mostly 🦗. In any case, we can write docs at anytime, whether or not it's a Plone event, although I appreciate good company and a free lunch at events. @fredvd please chat with me in Discord before you spend time on creating a separate issue and subissues or subtasks. I think I can save you some time and effort. |
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 pages, or only their TODOs if the page has content, will be purged. If there is not an existing issue in the issue tracker, one must be created for it, except for obsolete TODOs, such as Upgrading Plone 4.x to 5.0.
conf.pyand possible PST.@plone/volto-team @plone/restapi-team @plone/ci-team @plone/classicui-team @plone/marketing-communications @plone/documentation-team @plone/developers
The text was updated successfully, but these errors were encountered: