Create end-user Editor documentation

[stevepiercy]

What if we had end-user Editor documentation for Volto? And then in the UI, we could place the universal help icon (❔) that links to the relevant Volto Editor page in the docs, based on the context. This would keep the UI clean and leave space for future development. PyCharm does that for its UI, and it is super helpful to me.

Additionally this would create something for directionless newbies to work on that is relatively easy. These docs would be perfect for newbies. We could tag an issue with "33 needs: docs" and "41: lvl easy" to give a good entry point for them.

Originally posted by @stevepiercy in https://github.com/plone/volto/issues/3811#issuecomment-1298030528

[stevepiercy]

Hidden Editor gem: https://github.com/plone/volto/pull/3815#issuecomment-1301020379

[stevepiercy]

Undo: https://github.com/plone/volto/pull/3815#issuecomment-1298005656

[stevepiercy]

Add block: https://github.com/plone/volto/pull/3815#issue-1430794104

[stevepiercy]

From Discord: https://discord.com/channels/786421998426521600/862642144401031188/1042085679091425363

Drag and drop file upload: You can drag an image from your desktop file browser (Windows Explorer, Finder, whatever) to a Volto slate text block, and it will upload and create an image block for you.

Copy and paste file upload: You can paste an image from your desktop clipboard to the slate text block. So, on my desktop, I open the screenshot tool, I click "Copy to clipboard", I paste inside an empty text box (using ctrl+v), and I get an image block.

[stevepiercy]

https://github.com/plone/volto/issues/3679#issuecomment-1312380808:

It is possible to use the arrows to escape the Slate (only if the next block is also a slate, though this is an unfortunate decision that maybe we can fix).

[spereverde]

@stevepiercy is there a folder foreseen for end-user docs?

[stevepiercy]

Nothing has been decided yet, and it is up for discussion.

For Volto, I suggested a new directory and index, /volto/docs/source/user-manual/index.md, to get started. A volunteer stepped up in Discord, SonGoku#8071, in the #newbies-introduction channel, to start on this.

There may be other audiences to target in Volto docs, but for now we have identified Developers and Editors.

We also might need to consider whether this documentation belongs under Volto or the main documentation. For now, I think keeping it in Volto gives it a better chance of getting written and better integrated with Volto developer docs.

[MAX-786]

Thanks, Steve for mentioning me here...😊 I think I should consider changing my discord username tho😂 -SonGoku

[kenmanheimer]

I have a few user notes I'd like to preserve in anticipation of the proposed documentation. Being unsure where to put stuff while that effort is ramping up, and similar to notes I see above, I'm going to paste them here. Sorry if it's the wrong place - please let me know what the right place is, and I'll be happy to add them there.

Block copy, cut, and paste (from https://github.com/plone/volto/issues/4056#issuecomment-1339986567)

@tiberiuichim made a brief video showing the functionality: https://www.youtube.com/watch?v=wojij3xU_h0

Some things to note:

• Click in a block where you want the selection to start.
  • Use shift-left-mouse to extend the selection to another block
  • Use ctrl-left-mouse (maybe cmd-left-mouse on Mac?) to toggle the selection of that block or another block that's been selected.
• Use the copy/cut/delete icons that show in the left sidebar when stuff is selected to copy/cut/delete. (Ctrl-C / Ctrl-X / Del don't yet work.
• Once you've copied or cut a Paste icon will show instead. You can use it to paste in an empty block on the current page or navigate to another page to paste there.
• (Note that this also provides a way to (effectively) move a block into or out of a composite block that otherwise doesn't provide for drag-and-drop moves from the outside.)

List Blocks (unordered and ordered lists, and combinations thereof)

Dividing list blocks

• You can divide a list block by dedenting a list element (using Shift-tab) to zero.
  • When you dedent a non-empty list element (by using Shift-Tab) to zero, that element is changed into a separate text block containing the text that was in the list element.
  • If the list element was the last in the list, then the new text block is added after the last block. (This is handy for adding blocks after lists, which otherwise don't provide the means until https://github.com/plone/volto/pull/3815#issue-1430794104 lands.)
  • If it's the first element, then the new block is created before the list block.
  • If it's between the first and last elements, then the new block is created between two list blocks, the above one containing the elements that were before where you divided the list and the block below containing what was after where you divided the list.

Changing list block element types (unordered vs ordered)

• You can change the type of a list block element by highlighting some text and using the highlighted text menu to select the other list element type.
  • If the list element is the only one at its depth, then you will have started a nested list of the opposite kind from its containing list elements.
  • If the list element has any adjacent list elements at the same depth (peers) then the list will be divided into separate blocks, between the list element you're changing and its peers.
  • (Until https://github.com/plone/volto/pull/3946 lands you can't use Markdown gestures, per #4054.)

[stevepiercy]

@kenmanheimer thank you for adding these to the list of undocumented editor features.

We have not yet finalized the structure of the Editor Docs for Volto, but in my recent review of PR #4027, I suggested that we emulate what has already been done with Classic UI in Plone 5.2 documentation and adapt for Volto. For example Volto uses Slate, not TinyMCE.

[tiberiuichim]

On the topic of multiblock copy/paste, there's another feature that's not documented: when clicking the Paste button, if you hold the Ctrl (or Meta) key, you don't clear the clipboard: https://github.com/plone/volto/blob/99b51b9b3011889612fe97f01523cd4332b0c910/src/components/manage/Form/BlocksToolbar.jsx#L127

[stevepiercy]

Add / to set an empty block's type. See https://github.com/plone/volto/issues/4061

[MAX-786]

Hello @stevepiercy, (srry I was away for a while :) but in the meantime), I have gone through almost every section of User-manual for Plone5 and got a grip on how our User-manual for Plone 6 should be structured and accordingly made a proposal (covering many topics) but before I present it in a PR (if none is made by someone), I have few questions:

• There are some topics in Plone5 manual (like Conceptual overview, Logging In etc. ) which are common for Plone6 and making our user jump from plone6 user-manual to plone5 is not a good idea I guess. So, can we copy such topics (with minor chnges) from Plone5 to Plone6 (they are already so well written)?
• Does Plone 6 (Volto) have Portlet / Portlet Management section? I think I have missed it.
• There are some Plone 6 Docs that have "Note" saying it's incomplete, but do we have something (To Do list, etc) which is keeping track of these incomplete docs? If not, can we create an issue with the Task List of all the incomplete docs linked to their respective page? bcz to me they seem lost in there.

I hope I am not bothering you with such a long comment :) Thanks!

[stevepiercy]

There are some topics in Plone5 manual (like Conceptual overview, Logging In etc. ) which are common for Plone6 and making our user jump from plone6 user-manual to plone5 is not a good idea I guess. So, can we copy such topics (with minor chnges) from Plone5 to Plone6 (they are already so well written)?

Note that the concepts in the Plone 5.2 docs Working with Content apply to both Classic UI and Volto frontends in Plone 6. However the implementations are totally different (click here, click there, and so on).

We already mapped out the direction for porting the Plone 5.2 docs concepts in Backend and its many issues. Content Types is one example of the plan. We are open to accepting modifications to that plan.

For Volto, let's focus on implementation details. The idea is to write those implementation details for the Editor end user, and add links to the concepts in the Backend docs. Does that make sense?

Does Plone 6 (Volto) have Portlet / Portlet Management section? I think I have missed it.

It does not. This is a difference between Classic UI and Volto. Volto has blocks, which Classic UI lacks. You might find other differences. And we should actually add the differences to the list of reasons for choosing Classic UI versus Volto in the Installation documentation.

There are some Plone 6 Docs that have "Note" saying it's incomplete, but do we have something (To Do list, etc) which is keeping track of these incomplete docs? If not, can we create an issue with the Task List of all the incomplete docs linked to their respective page? bcz to me they seem lost in there.

Issues already exist for most of what needs to be done. Each todo should have a link to its issue. If you find something specific that needs an issue, then feel free to create one.

[MAX-786]

For Volto, let's focus on implementation details. The idea is to write those implementation details for the Editor end user, and add links to the concepts in the Backend docs. Does that make sense?

oh getting it now, I am trying out the above mention features so that I can start covering them in user-manual docs. Also, I thought of descriptions for different Block Types, which I collected here in GDocs.

[stevepiercy]

That looks good so far. Please create a PR when you want a review.