Writing for learners: best practices for creating, developing, and maintaining self-paced learning resources

This is a talk I submitted¹ to Write The Docs Prague, September 15-17, 2019. The conference uses a non-anonymized CfP process with a simple Google Form. The CfP page is here.

Talk title

Writing for learners: best practices for creating, developing, and maintaining self-paced learning resources.

Talk abstract

More information here is better. Submitting a single paragraph won’t give us much to go on, but please no walls of text.

This presentation talks about a special kind of tech writing: creating and maintaining self-paced technical training content. This encompasses both prose for theoretical background information, and instructions for hands-on labs.

In this talk, I’ll go over

• special challenges (and advantages!) of self-directed over instructor-driven training
• video content, and why we don’t do it
• our rules for structuring theoretical content
• our approach for interactive lab instructions

This is rooted in 4 years’ experience in writing courseware used for learning complex technical topics (like OpenStack, Kubernetes, Ceph, and others) on an Open edX platform.

You’ll find the concepts discussed in this talk useful if you write courseware (of course), but I’d say they equally apply whenever you find yourself writing any content that is instructive, rather than descriptive.

Who and why

Who is this talk for? What background knowledge or experience do you expect the audience to have? What is the take away from the talk?

This talk is for anyone who, in a technical context, uses imperatives. I’ve been at least a part-time tech writer for the better part of the last 10 years, but I’ve written software documentation for only 4 of those – the majority of the remainder I’ve written courseware content instead.

Writing prose training content and lab instructions comes with its own unique challenges and its own (explicit or implicit) style guide. Since as courseware authors we communicate with our learners exclusively in writing, I believe I have good practices to share with other documentarians who might occasionally find themselves in the situation of writing lab instructions and test scenario descriptions, and I think there are equally many things that can learn from other talks and speakers.

Other Information

Any other information that might be interesting for us to know about you? Give a lightning talk last year, speak at a WTD meetup, or anything else interesting? Add it here.

I’ve never spoken at any Write The Docs conference, though I have done talks and workshops at multiple instances of linux.conf.au, LinuxCon (now Open Source Summit), OpenStack Summit (now Open Infrastructure Summit), the Open edX Conference, and others.

My team and I maintain City Cloud Academy (academy.citycloud.com), which runs on Open edX.