Closed relativityboy closed 6 years ago
Results
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.
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.
The title is the topic & focus. Suitable for a table of contents
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)
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.
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.
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.
The tutorial in detail, with each step titled & numbered as in LIST OF STEPS/OPERATIONS.
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)
A simple statement telling the consumer they're done.
Any issues that may require troubleshooting
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.
It's very important that the tutorials be both accurate and precise in their language.
function
something used within the clientapi call
or 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.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 ?!
includes title and what this tutorial trying to teach reader/user/developer
includes functions or api used and general overview of them
step by step explanation of the code
cd abc npm install npm run dev-server (dev) npm start
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.:
<- links to tutorial
<- links to tutorial
<- links to tutorial
<- current tutorial, does not link
<- links to tutorial
@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.
@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
description
and skill acquired
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
I like new structure more, Intro combines Purpose and Description sections we previously had and move directly into Steps within tutorial...
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
Ok, final version is here https://github.com/steemit/devportal-tutorials-js/blob/master/tutorials/tutorial_structure.md
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