[SuperEditor][Web][Guides]: Updates guides for version 0.3.0 (#2429)

[suragch]

This PR aims to update all of the SuperEditor web guides to work with super_editor 0.3.0 with an eye for first time users.

Since I myself am a first time user, my goal is to write the docs that I would have wanted to have. They should not only help the reader to write code that runs but also explain any confusing aspects along the way.

I'm initially submitting this PR as an update to a single guide (SuperEditor Quickstart) for early feedback and will then ping the reviewer at various intervals afterwards (after every guide to start with). The PR doesn't need to be merged until all of the guides are finished.

[suragch]

@matthew-carroll

My changes to the quickstart guide will be a good test to see how much you'll allow me to change the current wording. The former wording wasn't bad, I just expand it. I'm also following these principles:

• As much as possible, I'll include entire code blocks that are copy-pastable. This will help users to get started quickly and avoid ambiguity.
• I'll include optional pieces like @override. Leaving them off may save a few lines, but the result is compiler warnings that makes the tutorial experience not quite as nice.
• I'll tell the reader what to do before the code block and add explanation after the code block to illuminate any confusing parts.

Is it OK to use backticks (`) rather that <code></code>?

[matthew-carroll]

Left comments on the initial adjustments to quickstart.md.

To your question about <code> tags. Yes you can use backticks instead. In fact, you should only use HTML tags in Markdown when you have no other choice.

[suragch]

@matthew-carroll
I've updated the Document from Markdown guide. Do we need to provide special instructions for importing the super_editor_markdown package? It doesn't work as directed in the guide. A dependency override is necessary. Is that always going to be required?

[matthew-carroll]

A dependency override is necessary.

@suragch - Is this actually true, after our recent conversation on Discord?

[suragch]

@matthew-carroll I've updated two more guides (Assemble a Document and Markdown Parsing). Unfortunately I did that before going through your comments above, so I made some changes that probably weren't in line with your idea of what the guides should be. You can respond to the changes in those guides and I can retract the tutorial style changes I made.

In the remainder of the guides, I won't attempt to make many changes. I'll just fix broken syntax. If I write a beginner's guide in the future, I can write it on my own site.

[suragch]

Is this actually true, after our recent conversation on Discord?

Our Discord discussion resolved the issue.

[suragch]

@matthew-carroll In the Add a Popover Toolbar guide, there is the following line:

_toolbarAligner = CupertinoPopoverToolbarAligner(_viewportKey);

CupertinoPopoverToolbarAligner doesn't compile for me and I can't find it or a good substitute in follow_the_leader. What is the current way of doing this?

[suragch]

@matthew-carroll

I've reverted several of my previous changes. Partly I had misunderstood the scope and purpose of the edits I was making. The other part was I let my pride get the better of me and tried to argue my side when that wasn't what you wanted for this site. I forgot that I'm here to be a learner. I'm sorry about that.

I've left in a few TODO questions. If you have any answers for those, I'll add them in. Otherwise, we can ignore them.

I wasn't able to get the Popover guides working. (See my question above about that.)

The Add New Type of Content and Add a Mobile Keyboard Toolbar guides are essentially empty. Should we remove those from the menu for now?

I'll limit this PR to the Super Editor guides. If I update the Super Reader or Super Text Field guides, I create a new PR for them later.