Basic structure to write a beginner tutorial (#114)

* Added basic structure of how the tutorial will be written * Added concepts section * New file creation * updated new tutorial * Removed a non template file * Updated changelog and version * Updated notebook and added it to tutorials.rst * Converted guide to rst file and linked in tutorials.rst * Small update * Updated changelog * Updated changelog and version * Changelog format fix * edits * formatting Co-authored-by: Will Cunningham <[email protected]>
AgnostiqHQ · Feb 18, 2022 · 296b999 · 296b999
1 parent 57366a9
commit 296b999
Show file tree

Hide file tree

Showing 4 changed files with 46 additions and 2 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.24.21] - 2022-02-18
+
+### Added
+
+- RST document describing the expectations from a tutorial.
+
 ## [0.24.20] - 2022-02-17
 
 ### Added
@@ -189,13 +195,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - UI: display error message on failed status for lattice and electron
 
 ### Changed
+
 - UI: re-order sidebar sections according to latest figma designs
 - UI: update favicon
 - UI: remove dispatch id from tab title
 - UI: fit new uuids
 - UI: adjust theme text primary and secondary colors
 
 ### Fixed
+
 - UI: auto-refresh result state on initial render of listing and graph pages
 - UI: graph layout issues: truncate long electron/param names
 

diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-0.24.20
+0.24.21
diff --git a/doc/source/tutorials/tutorial_guide.rst b/doc/source/tutorials/tutorial_guide.rst
@@ -0,0 +1,36 @@
+****************************
+Tutorial Writing Guide
+****************************
+
+This guide covers best practices for Covalent tutorials. These principles are indended to guide but not constrain the author.
+
+Set the scope
+-------------
+
+Good tutorials are small and self-contained. They do not overcomplicate things and cater to a mixed audience. Any examples highlighted should be straightforward and friendly to beginners.
+
+Introduce the example
+---------------------
+
+Introduce background material and describe what we will be trying to achieve in the tutorial. Separate the logical components and show what purpose each of them serves.
+
+Prototype the solution
+----------------------
+
+Write code with commented explanations wherever necessary. Write it without Covalent, in a functional manner, where it is clear what each of the components is doing in the context of the example.
+
+Run the workflows
+-----------------
+
+Add decorators to the functions without changing their definitions. Show representative screenshots of the UI to help readers understand the problem being solved. A good tutorial also provides typical input parameters and the corresponding typical runtimes.
+
+Analyze the results
+-------------------
+
+View the results in the Covalent UI, and query them programatically as well.  Summarize the findings using a meaningful plot or chart. Discuss the metadata returned in the result object.
+
+
+Discuss the concepts
+--------------------
+
+Highlight how different components of Covalent are used to accomplish objectives or to obey constraints.
diff --git a/doc/source/tutorials/tutorials.rst b/doc/source/tutorials/tutorials.rst
@@ -13,4 +13,4 @@ The following tutorials demonstrate examples of how Covalent is used in real-wor
 
 ---------------------------------
 
-Do you use Covalent in an interesting project? Contribute a tutorial on `GitHub <https://github.com/AgnostiqHQ/covalent/issues>`_.
+Do you use Covalent in an interesting project? Contribute a tutorial on `GitHub <https://github.com/AgnostiqHQ/covalent/issues>`_.  To get started, check out the :doc:`guide <tutorial_guide>`.