Software Engineering at Home

# 📝 Writing Guide

# Intro

Consistent, interesting, and digestable information. This structured writing guide will help you produce content; it can be used as an ordered checklist, and as a scoring mechanism to generate high quality content.

# First Steps

To get started, make sure your idea has a place in the TOPICS.md index - all that's needed is a title on a new line; find the right specialism to group it under - make a new specialism if breaking new ground. This is a great stage to save, commit, and push the change up to the public repo.

Next, when you're ready, make a markdown file from WRITING-TEMPLATE.md; don't worry about filling the details at this stage.

Finally, link to your new markdown file from TOPICS.md to show that you're working on it.

# Checklist

  • ☑️ Content idea added to TOPICS under a specialism
  • ☑️ Markdown file created in sub-folder using WRITING-TEMPLATE.md
  • ☑️ Link to new markdown file from topic index

# Why

Finding a video or article online, and knowing that this content was precisely made for you.

Following Simon Sinek's "Start with Why" (opens new window) the all important Why sells a vision of why you should care about this content; people can find out about the what, and the how after they become interested. A compelling why lets people know the benefit they will receive for sticking with the content, by painting a story in their mind.

# Checklist

  • ☑️ The topic has a written Why section
  • ☑️ Describe why the audience should engage with the content

# How

Reading these slides, and watching the online commentary.

The How describes the process - specific actions that get you from the Why to the What. Use this section to describe tangible actions that the audience can take to enhance their knowledge and skills.

# Checklist

  • ☑️ The topic has a written How section
  • ☑️ Describe how the audience will learn about the topic

# What

Once the audience know the Why, and the How, we can finally establish our knowledge of the outcome - the What.

The What is the result, the proof, the evidence of the end result. Use this section to highlight learning outcomes, and practical results of case studies.

# Checklist

  • ☑️ The topic has a written What section
  • ☑️ Describe what the audience will gain after completing the topic

# Supporting Material

By following the format of the Writing Guide, and the Writing Template - you should already have a slide deck prepared.

You should also take the time to draw at least one diagram supporting the explanation to help visulise the content and consider the unwritten words surrounding the topic.

Ideally the topic will reference multiple sources such as articles, books, papers, practical exercises (katas), or videos.

For example:

# Checklist

  • ☑️ The topic has a supporting slide deck
  • ☑️ The topic has at minimum one diagram supporting the explanation
  • ☑️ Link to at least two other sources of relevant material online

# Conclusion

So finally; let's review all that great writing advice:

  • ☑️ Plan to make great discoverable content
  • ☑️ Start writing
  • ☑️ Think about the Why
  • ☑️ Think about the How
  • ☑️ Think about the What
  • ☑️ Provide supporting material
  • ☑️ Conclude firmly

# Where next?

You probably want to go back to the 📚 Topic Index !

← 📋 Writing Template →