​​Tutorial Blueprint

​​Write-up Guidelines

​​Markdown

​​

​​Content

​​Preparation:
  • ​​Is this a tutorial for beginner, intermediate or advanced developer?
  • ​​What prerequisites should the developer know of?
  • ​​What is the end goal?
  • ​​What steps would developers take to accomplish the goal? 
  • ​​What steps could be recorded/animated? Some developers are visual learners
​​
​​Structure:
  • ​​Introduction: Why is this important? What is the end goal?
  • ​​Preview: Illustrate the final outcome (video/website/screenshot/diagram)?
  • ​​Provide a link to the final result 
  • ​​What you’ll learn: In a few bullet points, what skills will devs gain form this?
  • ​​Duration: How long will it take to complete the tutorial?
  • ​​Prerequisites: What should the dev know? What should be already be installed, configured or set up? What tutorial should they have finished?
  • ​​Step 1-X: What are the steps required to accomplish the goal? 
  • ​​Add explanations why something is important to know
  • ​​Ask yourself if everything you mention is either a) well explained or b) irrelevant
  • ​​Preview the result for the end of each step
  • ​​Congrats: Congratulate the dev on completing the tutorial. What did they learn again?
  • ​​Next steps: Where can the developer go from here? How to advance and leverage the knowledge from this tutorial?
  • ​​Related links: Where could developers learn more in depth about libraries/concepts/tools used in the tutorial?
​​
​​Writing:
  • ​​Link to existing references wherever applicable
  • ​​Leverage notes (“> Pro Tip: “) to communicate nice-to-knows (e.g. advanced tips)
  • ​​Add source code of most relevant parts. Never take screenshots of sources
  • ​​Try to always use inclusive language (avoid assumptions on knowledge, demographics, and more)
  • ​​Describe each step required as part of the tutorial. Linking out to other tutorials for some steps is a bad practice
​​