Writing for the Learning Portal

The Crunchy Data Learning Portal contains interactive tutorials for learning PostgreSQL. It provides a complete learning environment where the user can focus on “learning by doing” without needing to worry about setting up their own apps, utilities, etc. The learning portal is powered by Katacoda.

Guidelines

Keep it focused

We have multiple courses in the learning portal, and each course can be made up of different scenarios. Each scenario is then composed of steps.

Each step will open in the browser accompanied by an interactive terminal (and optionally an additional terminal window depending on the scenario). Since the instructional text shares screen real estate with the terminal, that means each step may look longer than it really is. The user may need to scroll down to finish a single step.

Avoid long walls of text. If the step becomes so long that the user ends up scrolling too much, consider breaking it out into smaller individual steps.

Don’t assume expertise

If you are creating a workshop, course or scenario for a specific group that you know very well, you might be able to tailor the narrative to them. Otherwise, you should assume that you are writing for a complete beginner. Be clear when providing instructions and feel free to add supporting explanations as you go (e.g. why is a particular step necessary, and why does it have to be done exactly in that way?).

Connect with existing material

There might be other material (such as docs or blog posts) that could be helpful for the user to read. Feel free to include links and make sure to briefly describe what they are.

Formatting

Call out important information with bold text, or consider using quotation blocks for longer text:

Note

Please read carefully as this is important information for this task.

Headings

Organize text with H2s and H3s. Use H2s for higher-level topics or goals and use H3s within each section for supporting information or tasks.