The learning platform has two types of articles: guides and tutorials. Each has a distinct style and set of best practices, as well as different use cases.
Guides
A guide is designed to consolidate resources on a topic, in order to make them more accessible for SIMS members. Guides don’t necessarily walk people through how to do something, so much as to help them find the most relevant information. Examples include style guides that help us keep our products visually streamlined and standard operating procedures to ensure we’re all on the same page about our shared processes.
Structure of a Good Guide
- As evergreen as possible: Guides should be written in such a way as to keep the content as useful as possible for an extended period of time. Don’t document a process that will likely change or not be applicable in other contexts.
- Link to existing resources: Guides should not be reinventing the wheel, but instead using existing resources that are available from the Movement or from similar organizations that work in the international humanitarian information management space.
- Show examples: If creating a template for something like a map layout, show examples of final products that used the template. WordPress allows files to be directly uploaded to the learning site.
Tutorials
A tutorial walks readers through the process that you went through to create a product or solve a problem, and that you think could benefit future remote supporters. Tutorials break down the solution into distinct steps so that people can either follow along to recreate a similar product, or learn your method so that they could remix the final product to suit their own needs. Examples of tutorials include step-by-step guides on creating a new type of map produced for an operation and a completed mobile data collection XLS form with a write up about how it was developed.
Structure of a Good Tutorial
- Break down your steps: Don’t yada yada yada past the details! Write your tutorial in a way that you’d explain the topic to a complete beginner. More detail is better than less.
- Use screenshots: Whenever possible, include screenshots of your work. If you’re working inside a program like QGIS, it might be overwhelming to share the entire window—try to focus on the area most relevant to the step you’re describing.
- Leverage other guides: If your tutorial made use of other resources—either on learn-sims.org or elsewhere on the internet—be sure to link to them. For example, if you made use of a tutorial someone else made for a step in your process, link there so others can see it. This also helps you avoid duplicating that effort.
Checklist for Publishing
- Review: Has at least one other person with write-access to the learn-sims.org site reviewed the article for content and to check for typos?
- Clear headers: Have you organized the document into clear headers and subheaders to help readers find relevant sections? The WordPress editor interface divides content into blocks. When you create a block to hold a section header, use H2 for the main sections (these are the top level headers that will appear as elements in the table of contents on the right side of the page) and H3 for the subsections nested under each H2. You can go deeper than that (e.g. H4) but they will not appear in the table of contents.
- Excerpt: Have you provided a short one or two sentence summary of the document to help readers quickly understand what it covers? The WordPress doc edit page has a text box where you can enter a short blurb that describes the guide’s content. Be sure to include a single, descriptive sentence that explains at a high level what readers can expect from the article.
- Tags: Many tags will already be available, so only add ones that you think will be useful for helping others find potentially useful guides. A tag might be used for the tool (e.g. Illustrator or Python) or a process (e.g. scenario planning or assessments).
- Author byline: Have you added a block at the bottom of the article, set to “Custom HTML”, and pasted this code into it: