Follow the steps in a Simple Chat App and clarify them in the doc

[Annamarie2019]

[Annamarie2019]

@johnnymatthews How's this as a step towards clarifying the simple Chat App article? Then Discordian could ask about each point and know why it's being suggested. (Notice I suggest a demo.)

Here is a link to a cut and paste of Discordians original blog into Google docs with some comments: https://docs.google.com/document/d/1UDjnMEBQSeDwm6iQQeStxSHjmcZmyi4-3FsExGAylxw/edit?usp=sharing

Here are some ways to help this app get the appreciation it deserves, with some doc usability techniques:

• Concise INTRO: The introduction needs to explain the UI all in one place, so the reader isn't jumping back and forth.

• Put the Easy path (just accepting the app as-is) into the Intro, someplace separate from where the user is trying to focus on customizing: Could be included as part of the intro.

• MAJOR: CUSTOMIZATION STEPS SEPARATED OUT: The steps need to be brought out, possibly as numbered steps, so the user can follow them in a more user-friendly way, instead of searching through the text for action items. The actual steps are highlighted in the Google doc (link above).

• CONCEPT section....in intro: If the steps are brought out, we'll want to put whatever concepts are general up top, so they don't distract from the steps, and only have concepts they need to execute the steps as paragraphs after each numbered step.

• Clarify which CODE SAMPLES demonstrate a place where the user has to customize something and which code is just informing them what we do for them. We should be really specific about exactly what we're suggesting that they customize (like the star nodes)....not say "things".

• Rephrase any passive voice to active voice, so we know who the actor is (us/system or a step for the user to take).

• Use LINK DISPLAY TEXT that is meaningful. Users often scan the doc for the links. Scanning across "here" is not helpful.

• Demonstrate EASY & SIMPLE, don't claim: The article uses the word "simply" or "easy" about 12 times, a known doc-usability practice to avoid. (Better to demonstrate ease of use, then claim it. It makes users mad when it's not easy for them, which could be often if the steps aren't clear or even just bc it's new to them.)

• Remove DOCKER: On page 3, Discordian agreed that we should take the Docker option out, as they keep changing that page so it's unreliable.

• Make sure any three-letter acronyms are spelled out.

We need Discordians help with:

• A DEMO of the steps would be excellent to make sure we capture everything in the right order. Would be best if this is a recorded Zoom meeting, so the writer could refer back to it and not have to keep asking Discordian.
• Broken link on page 1.
• Diagram on page 3 may not add to the user's understanding. It seems like a distraction as they search for what to DO.
• On page 8, there are supposedly some new steps for WebSocket that we need.
• On page 9, there is a step about SSL that is out of order. It needs to be clarified. It mentions "domain name you got the SSL cert for," and SSL is below this.

[Annamarie2019]

It looks like we kept the rewrite that was recently done, which does a lot of the above. Here are the things that remain to be done:

• We could use a step-by-step version of this article. We could either rewrite the current one with steps, or create a separate article with only the steps for customizing the chat app. (Right now they have to search through the text to figure out what to actually do.)

• Rephrase any passive voice to active voice, so we know who the actor is (us/system vs. a step for the user to take). Passive voice really kills the simplicity of the app and makes it seem complicated.

• Clarify which CODE SAMPLES demonstrate a place where the user has to customize something and which code is just informing them what we do for them.

• We should be really specific about exactly what we're suggesting that they customize (like the star nodes)....not say "things".

• Diagram on page 3 may not add to the user's understanding. It seems like a distraction as they search for what to DO.

• We need Discordians help with:

• A DEMO of the steps would be excellent to make sure we capture everything in the right order. Would be best if this is a recorded Zoom meeting, so the writer could refer back to it and not have to keep asking Discordian. In the blog, Discordian refers to something "above" which is actually below.

• Broken link on page 1.

• On page 8, there are supposedly some new steps for WebSocket that we need.

• On page 9, there is a step about SSL that is out of order. It needs to be clarified. It mentions "domain name you got the SSL cert for," and SSL is below this.

Recommended Format:

• Template: Intro text, Setup, Steps, Outcome:
  • Follow the classic how-to format of Introduction, Prerequisites or "One-time setup", Steps or "Run the Code", and Outcome or Output.
  • For an example, see this article that I wrote: Confirm deposits to an Exchange.
  • Have an overall Outcome for the entire process.
• Subsections:
  • Under "Run the Code," have 4 subsections for each part (Get the Code, Discovery, Advertising, Communication.)
  • Have numbered steps under each subsection.
  • Have an Outcome for each subsection.
  • Here's an example I wrote with subections: Axelarcross-chain dApp examples (They each have an "Outcome"--in this case "Output"--but, since all the steps are the same--Deploy and Test, with an example--no numbered steps).
• Reference info and Optional steps at the bottom, so they don't complicate the main message.