[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?

[matthew-carroll]

I think the term "add" is misleading. That makes it sound like some "extra" thing you tack on to an Editor. A Document is a foundational requirement for an Editor.

I think if you want to point people to the Quickstart guide, then we should just do that and not recreate the example code. On the other hand, if you think the example code is needed, then I don't think we need to reference the Quickstart guide. Or at least we don't need to reference it up here above the example.

Here's another version of this part of the guide based on my thinking above:

The de-serialized document is a `MutableDocument`, which can be queried for content, and also mutated to change the content.

A `MutableDocument` is typically used within an `Editor` to implement document editing with user selections, change events, reactions, etc.

    _editor = createDefaultDocumentEditor(
      document: document,
      composer: MutableDocumentComposer(),
    );

To learn more about initializing and displaying a document editor experience, see the [Quickstart Guide](/whatever).

[suragch]

Since people presumably just finished reading the Quickstart guide, my thinking is that we don't need to re-explain what a MutableDocument is. I thought having a quick refresher on where to use the document object would be helpful, though.

I take your point about the "add" word, and including a link is a good idea.

But if you would prefer to remove the code block or add the extended explanation, I can do that.

[matthew-carroll]

All code is intended to be run, so instructing the reader to run code doesn't add anything. Additionally, if the user does run the code in the sample, the user won't see anything. So this statement isn't accurate.

[suragch]

I'm not sure if you noticed that I had added the block:

const markdown = '''
# Header
This is a _Super_ Editor!
''';

I did that so that this guide would work more like a tutorial and running the code would produce a visible result. The code in some of the other guides don't run as written. For example, document.deleteNodeAt(2) in the Assemble a Document guide was a code fragment meant to be used as an example and not meant to be run as a part of a tutorial (since 2 would have been out of range). "Run that" is a signal to the user that given code is tutorial style rather than a random snippet, and they should be able to try it out.

Also, the current Quickstart guide that is live now says "Run your app, tap in the editor, and start typing!" I was following this tutorial style pattern.

Is your intention for most of the guides that they should just be code snippets rather than tutorials?

[matthew-carroll]

We should avoid implying knowledge about orders of sections. At any time we might choose to re-order sections, add sections, or remove sections. A section is meant to describe an isolated concern, so it shouldn't be difficult to avoid referencing things that come before or after.

In this case, it doesn't look like any additional information was conveyed by the addition of words. If you feel that the existing sentence doesn't provide enough context, then you could elaborate on context. But if the existing sentence actually communicates all relevant info, then it probably doesn't need to change.

[suragch]

I think I misunderstood the original intent in updating the guides from a new user's perspective. I was updating them as if I were working through the guides as a new user reading them in the order they appear in the menu and reading each guide from top to bottom. I see now that that was not your intention.

[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?