First, I would make the numbered items in the lead-in be hotlinks to the two sections. The Insert set are far enough down the page that this could save some scrolling.
Second, especially for new users, I would note in the Action section that this same action gets inserted by FOUR different items in the Action menu:
- Display Text
- Insert Styled Text by Pasting
- Insert Text by Pasting
- Insert Text by Typing
(The above is the order they appear in the Action menu, alphabetical, but I agree that it's clearer to explain the three Insert Text versions in the order that's already there.)
This then leads into the illustration of the Action Choice Menu that's already there.
As I mentioned previously, it would be nice to offer some insight on why two such seemingly different functions are handled by the same action. It seems counter-intuitive that they are the same function. @JMichaelTX makes the same point. But "Peter's Preference" is a legitimate reason and probably doesn't need to be stated explicitly.
I think JM's other suggestions are good.
Screen shots for Display Text Briefly and Display Text Large would be helpful for new users.
At the very least, it would help new users if the doc repeated that there are two different contexts, at the beginning of each section.
Screenshots and examples for the Insert half of the functions would be nice, but the minimum would be a short explanation of what actually happens.
- Insert text by typing -- Adds the given text to a text field at the current active location, one character at a time, as if typed on the keyboard.
- Insert text by pasting -- Adds the given text to a text field at the current active location by pasting the entire text at once, as plain text. Also leaves this text on the System Clipboard for a repeat paste action.
- Insert styled text by pasting -- Instead of plain text, insterts RTF (or whatever -- what IS it?) text that includes fonts and paragraph styling. Also leaves this entry on the System Clipboard.
A definition of what the format is of the styled text would be nice, RTF, HTML, Apple Internal, etc.
I hope this helps,