Update 'Readme' Structure Spec for Tutorials & Recipes

[relativityboy]

The tutorial guidleines in steemit/devportal#46 are very good, but as the devportal and tutorials evolve, we may need a different standard that extends the description in 46 and leverages some of our new infrastructure.

This story does not attempt to address the filesystem of a tutorial

AC

• [x] Create an updated set of guidelines that are readily followable by developers creating tutorials, and optimizes both consumer understanding and development effort.
• [x] Results are in a comment on this issue titled Results
• [x] All Steemworks developers agree to the approach

[relativityboy]

Results

GENERAL TUTORIAL/RECIPE GUIDELINES

Use https://github.com/steemit/devportal/issues/46 as partial reference where this doc is ambiguous (referred to after as 46). Please note that all visible structure is contained in the STRUCTURE section.

PURPOSE

Tutorials must be focused on a specific task, practice, or theory. The consumer of the tutorial should come away with enough knowledge to perform the task, follow the practice, understand the theory.

STRUCTURE

TITLE

The title is the topic & focus. Suitable for a table of contents

DESCRIPTION

The description goes into greater detail. It is intended to help the consumer decide if the tutorial is appropriate for consumption. This may include examples of applicability (where the operation(s) in this tutorial would be useful)

SKILL AQUIRED PARAGAPH (described as 'goal' in some curren tutorials)

Defines clearly the knowledge/skill aquired by successfully completing the tutorial. If there are areas of likely interest that the tutorial does not cover, that is explained as well.

ENVIRONMENT SETUP & RUN INSTRUCTIONS

Describes the running environment (may link to external doc for brevity) with the final "run" instruction(s) listed here, as well as any tutorial specific configurations or settings. If the tutorial/recipe does not have runnable code, states that.

LIST OF STEPS/OPERATIONS IN THE TUTORIAL

If there are 2 or more steps to the tutorial an in-order, titled and numbered set of steps. Description not needed. If there are 'complication' scenarios as described in 46, those are enumerated here.

TUTORIAL

The tutorial in detail, with each step titled & numbered as in LIST OF STEPS/OPERATIONS.

TUTORIAL STEP

Each step describes what happens in that step. A step may be a "primary" step ex: 1. or a "secondary" step 1.a. A step includes no more than one api call. If there is an api call, there is a code block with the title "Query" showing the parameters for the call, and at least one code block titled "Response" showing a possible response from the api (multiple possible responses may be shown, so long as they are numbered/labels and there are adequate descriptions of each response & why it would be emitted by the API)

DONE STATEMENT

A simple statement telling the consumer they're done.

Troubleshooting - optional

Any issues that may require troubleshooting

FOOTNOTES - optional

A section for any caveat, gotchas, references. The 46 Simple Arguments, Advanced Arguments, & Expanded Results should be able to point to Steem's API specification in the devportal for the relevant calls. If the specification isn't clear enough, it needs to be updated.

LINGUISTIC PRECISION

It's very important that the tutorials be both accurate and precise in their language.

• a function something used within the client
• a api callor rpc is a call made between the client and the server. Ex in client.database.call('get_active_votes', [author, permlink]) is an api call and should be referred to in a manner similar to _the rpc get_active_votes ..._. When referencing .call() it is a function.
• tags that take the user to a different page/site should be referred to as links
• or any other elements that are hooks for javascript should be referred to as controls ex: Clicking the "go back" control will show the article list. this section will require updating as we find other points of ambiguity

I like the structure, this might require us revisiting all previous tutorial READMEs and updating them in next sprint. Some/most tutorials are simple and having above structure might be repetitive in some ways, for example purpose, description and list of steps will most likely be same, imho. Maybe this is simpler, @relativityboy ?!

Purpose

includes title and what this tutorial trying to teach reader/user/developer

Description

includes functions or api used and general overview of them

Tutorial steps

step by step explanation of the code

How to run

cd abc npm install npm run dev-server (dev) npm start

[inertia186]

I think @feruzm has a point. If a tutorial is essentially and fundamentally a "child" (or extension) of a previous "parent" tutorial, it can include a link to that previous tutorial and only use this simplified structure. One addition I would recommend in the simplified structure is to have a mini-map of all related "child" tutorials under that topical umbrella, e.g.:

• How to query a widget (parent) <- links to tutorial
  • How to query a widget with thingys (child) <- links to tutorial
  • How to query a thingy that has certain widgets (child) <- links to tutorial
  • How to query a widget that does a whooza on thingys (child) <- current tutorial, does not link
  • How to query a widgets grouped by whoozas (child) <- links to tutorial

[relativityboy]

@inertia186 - Linking a to a previous 'parent tutorial' is in essence describing the current tutorial as a complication from your original guidelines. If the complication is large enough, what y'all describe is jess fine.

@feruzm the structure you propose is illustrated nicely in [JS-08])(https://github.com/steemit/devportal-tutorials-js/tree/master/tutorials/08_get_account_replies). While an improvement over earlier tutorials, I think it leaves some gaps. I'll cook up a branch with some examples of my proposal as soon as I'm able. That will give us firmer ground to discuss.

[relativityboy]

@feruzm @roboza @inertia186 - Feedback please..

I updated steemit/devportal-tutorials-js#23 to follow a rough version of my original proposal. Even though it references 72 and not 23 in the commit. (oops)

Differences are

1. Swap description and skill acquired
2. Addition of 'Intro' section to give context and background.
3. Put run at the bottom as currently is (still might want to put this elsewhere)

Even though this tutorial doesn't link to the 'post' tutorial, I still support that, and the minimap idea.

New version of readme can be found at https://github.com/steemit/devportal-tutorials-js/tree/23-submit-a-comment-reply/tutorials/11_submit_comment_reply

[feruzm]

I like new structure more, Intro combines Purpose and Description sections we previously had and move directly into Steps within tutorial...

[roboza]

limit screenshots to 800px wide when taking the screenshots and when displaying it on the readme.

limit in devportal to render at 50% of original size

[relativityboy]

Ok, final version is here https://github.com/steemit/devportal-tutorials-js/blob/master/tutorials/tutorial_structure.md