Documentation feedback

[stevepiercy]

I am still struggling with serious painpoints in the docs. e.g. no Troubleshooting FAQ with common known mistakes you can get stuck with. I know GIYF but I am currently listing them for me and hopefully can contribute back.

1. Contributing to Documentation is currently buried under Contributing to Plone in the Table of Contents of the Plone6 docs.

2. Suggest edit is buried under the Github Octocat Icon at the top of the page (Icons without text need to be learned! In particular when the topic is a subtopic where icons simpoly do NOT work even if the purpose seems obvious for the sender, for the receiver definitely NOT, because it is lacking the context in the brain of the author. Therefore you have to be explicit as sender, when you cannot make sure the whole is communicated mandatory.

3. I would suggest to have a prominent permanent side tab with the unmistakable message:
   Improvement Welcome – Start here…
   and a repeated instance in the footer.

The whole text at about contributor roles and requirements is disencouraging as long as just pointing to misleading stuff as feedback is welcome. This is why these simple requests: Was this helpful as Star Ratings were created offering a freetext field to let your emotions run. Never ever let an input in this field touch your personal mood ;-)

One more point: The well understandable requirements for "First Time Contributors" are a bit of disencouraging as well for improving just docs. I started my first contributions to Plone with docs for the Plone 3 theming story by wrapping up stuff from listening in a workshop Denis Msihunov during the Naples Conference in 2007. Writing docs can jumpstart your understanding in an impressing way.

To get an idea what I mean visit this page from my archive thats is still present in the web:
https://opensourcehacker.com/2012/01/08/readthedocs-org-github-edit-backlink-and-short-history-of-plone-documentation/

This short wrapup of the procedure was present on every Docs page and lead me to my first docs contributions:

I hope I come back with serious improvements, but first I need to get this to run, run, run…

Please take this not personal!

Its not the correctness of the steps, but the elegance how to jump in as an easy going.

What is the best place to move this a bit distracting discussion from here?
On the other hand a proper cookieplone workflow can cut away efforts to describe troubleshooting by avoiding the mistakes upfront.

If we write and test docs having the knowledge of the development and docreading experience in mind and think further how to put this at the fingertips during cookieplone setup using a chatbot like experience could improve the setup successrate enormously.

Originally posted by @acsr in plone/cookieplone#50 (comment)

Important Note mentioning the inspiring work: The example shown above is the work of Mikko Ohtamaa, I mentioned earlier in this ticket here: plone/cookieplone#50 (comment)

[acsr]

@stevepiercy THX for moving this here and set it on track. I was thinking about removing it in the cookieplone ticket. But finally I think we need to encourage people to think outside of the box and show how a pain here can trigger a cure there. Dissatisfaction is the main force behind the design of good products or processes. The main difference between ordinary people and inventors and designers is taking the challenge and fix it. You can be proud to be part of the party!

«It is not important to invent something, it is important to recognize you invented something [... useful…]! – Thomas Edison

[stevepiercy]

@acsr let's figure out what we can do.

First I need to explain Plone 6 Documentation's current architecture, because it adds complexity that won't work with some of your suggestions. Its repository consists of its own content plus three other projects—Plone REST API, plone.api, and Volto—and their documentation is pulled in via git submodules. The first of those two also host their own docs on Read the Docs, and the maintainers want to keep it that way. It is very unlikely that there shall ever be a single repository that directly hosts all of Plone's documentation.

1. I'm trying to understand how you see this as a problem. If someone wants to contribute anything to Plone—whether that's docs, Plone core, or any of its subprojects—looking under "Contributing to Plone" is the logical first step. Perhaps you have a suggestion?
2. The Octocat icon has three dropdown options when clicked.
   • Repository goes to https://github.com/plone/documentation, which is a reasonable default.
   • Suggest edit is a bug. Due to the architecture of documentation as I explained above, I know of no easy way to have an "Edit this page" link or button that takes the user to the correct repository and page editing interface. The Sphinx themes on which Plone Sphinx Theme is based assume that all documentation resides in a single repository. Our intention was to redirect the user to Contributing to documentation, but that doesn't take the user to directly edit a page. I think this link should go away. If someone can figure out a way for that link to dynamically insert the correct repository and filepath to edit that page, then we can restore it. Meanwhile, folks can read the Contributing to Documentation guide. This link will get removed in Add documentation for how to administer Read the Docs for documentation and update Plone Sphinx Theme configuration #1667.
   • Open issue goes to the Documentation repository and pre-populates a New Issue form, which is a reasonable default.
3. See architecture of Documentation and Item 2 for why this is not possible.
4. See Revise Contributing to Documentation page #1779
5. I don't want to offer star ratings or comments from any visitor, as it raises expectations that they will receive a response. Most of it is spam and noise. We have an issue tracker that already works, as well as the Plone Community Forum and Discord. We don't have volunteers who want to handle it. Perhaps in a different industry where they have paid customer service staff it would make perfect sense, but not in Plone.
6. First Time Contributors has history. Plone projects, especially Volto, get flooded with crappy pull requests, issues, or comments every time a professor makes a class assignment for their students. 99% of these students don't bother to read anything about how to contribute to Plone, much less open source software in general. They just barge in with thoughtless comments such as "please assign me this ticket", or "where is file to edit?". Dealing with the volume and noise consumes valuable core contributor time. It used to be much worse until we addressed it with the First-time contributors guide. Many of us started to use GitHub saved replies to save time, whereas most others just ignored it.

I think I've addressed all that you brought up. If I missed anything, or you have some other actionable suggestions, I'd like to hear them. Thank you!

[stevepiercy]

@acsr I created a PR for Item 4 in my response: #1788. I would really appreciate your review to see if it solves most of what you brought up.

If you have no further feedback, I will close this issue as complete, after #1788 is merged. You can always reopen this issue with additional feedback. Thank you!

[stevepiercy]

Closing as complete. @acsr feel free to reopen and add feedback, if I missed anything.

[acsr]

@stevepiercy thx for the detailed explanation of some drawbacks of certain feature requests and existing limitations. Opening the ticket with the context in the ticket title is at least a good improvement.

I would still see something like the yellow patch (cited above) with an overview of the whole story under the octocat menu icon and like the link for the new ticket.

You can host a rewrite machinery to create links to the source page on github elsewhere.
The point is the discouraging effect of too much confusing detail information, when a contributor has to decide:

Am I willing to take the pain to dive through or do I get my fingers off?
If you discover the complexity just one step more far away, you have the chance to fall in love and stay in the first place.

At https://plone6--1788.org.readthedocs.build/ and the current version online I cannot detect the triple options for the octocat menu and therefore cannot test the "Suggest edit" issue. See my mention of the yellow patch (that can become blue ;-).

So far for now… Reopening makes sense if I can fiddle a prototype for the patch or someone takes over who got the final point: To make it easy and improve the quality, the process should be simpler to understand, not easier to ignore.

[stevepiercy]

@acsr I strongly disagree with the yellow patch concept for the following reasons.

1. It is far too obtrusive. It will interfere with people who just want information relevant to developing Plone.
2. It is misleading. We cannot accept contributions to documentation without either a signed Plone Contributor Agreement or an explicit statement assigning ownership of the contribution to the Plone Foundation.
3. Documentation consists of 4 separate repositories of content. An "Edit this page" link would need to be rewritten after the build process completes. It would also be misleading because it would bypass the required process described in item 2.

Unless and until the Plone Foundation removes the requirement of an assignment of ownership for any contribution, an "Edit this page" link in any form shall not be added.

[acsr]

@stevepiercy OK, got it.