Interactive AsciiDoc Training using Bowmann’s 4Cs

I regularly give presentations, now and then also trainings. To engage more with participants, I wanted to make them more interactive. The book “Training from the back of the room” was on my reading list for quite some time to help me with this.

Now that I’ve read it, this post summarizes my first two trainings that I structured using this approach. It was all about Bowman’s 4Cs: Connections, Concepts, Concrete Practice and Conclusions.

Activate their brains!

The concepts in “Training from the back of the room” help you to design a brain-friendly training that eases the learning process for the participants and make it most effective. You’ll see that it is effective when the participants engage in your training.

This works best when the trainer structures the training via the 4Cs:

Two more things are important:

• Make each exercise short: About 10-20 minutes are ideal. This helps participants to stay focused.
• Start with the end in mind: A training for firefighters should enable them to fight fires, not to pass a multiple-choice test about firefighting.

My first training TBR style

I wanted to teach people to write content using AsciiDoc. At a meetup at the Java User Group Passau in Germany there were about 16 participants, and I wanted to make it interactive using the concepts from “Training from the Back of the Room” (TBR). I expected all participants to be familiar with an IDE and editors, and to have some interest in documenting things (as they wouldn’t be in a meetup about documentation as code). I assumed that some participants would have have used a markup language before while others wouldn’t.

Starting with the end

As it was about writing AsciiDoc, I needed to find a solution on how to write AsciiDoc content as a group exercise. I pulled together my bits of JavaScript knowledge, and created a minimal browser based editor focused on trainings like this.

I called it “Anita Editor” (it needs to have a name, right?). It has the following elements:

• Text area on the left to write the AsciiDoc content.
• Preview on the right that renders almost instantly when changing the AsciiDoc content.
• Pre-configured to support diagrams via Kroki, source code highlighting for listings and nice admonition icons and call-outs.
• Last but not least: Invite any collaborator by sharing the editor’s URL.

For me as a trainer, this is now as simple as:

1. Open anita-editor.ahus1.de.
2. Enter a scratch name and press “Join”.
3. Paste a task description to the empty editor.
4. Share the URL in the browser with the participants as a group exercise.
5. Repeat for multiple group exercises; use the navigation bar to switch between different scratches.

Everyone can type, see others typing, and has a live preview. Browser-tech for the win!

Syncing via Websockets or WebRTC (if available) will work between participants that are online at the same time. The browser will save the contents so a participant will see it when they close and re-open the browsers.

Structuring the exercises

I wrote all exercises in AsciiDoc and pasted them into the editor. Each exercise starts with a quick example, a link to the docs, and then some tasks for the group to tackle. You’ll find all exercises in this GitHub repository. Click on a file, and then click on “raw” to see the AsciiDoc source code. Alternatively choose the pencil next to the file to open it in the editor in single-user-mode.

I prepared each of the exercises as a scratch in the Anita editor, so that the editor shows the source on the left, and the rendered preview with clickable links on the right.

This trains them three skills the participants will need day-to-day when working with AsciiDoc:

1. Read and comprehend AsciiDoc content,
2. learn to look up things in the AsciiDoc reference documentation, and finally,
3. writing AsciiDoc content.

Writing in this small web editor gives an immediate feedback to all participants. While the start is simpler than a real IDE, writing text is a different in two aspects:

1. It is a lot simpler, as they don’t need to handle Git, or learn other IDE controls. Also, collaboration is instant as each letter typed is transmitted to the other participants within milliseconds.
2. It is more difficult, as auto-complete, syntax validation and built-in templates that would be available, for example, in an IDE like IntelliJ aren’t available in the minimal Anita web-based editor.

Overall structure

As designing of the workshop started with the end in mind, here the full structure of the workshop at the Java User Group Passau:

1. Welcome to all participants.

2. Whiteboard exercise using MetroRetro to answer the questions:

   • What have you used so far to write documentation?
   • What went well?
   • What were obstacles?

   Once we’ve collected the experiences, some participants shared them in the call.

3. Presented with slides and a demo some context about AsciiDoc and an intro to the web-based editor.

4. As there were 16 people, we voted on the topics that were most interesting for the group exercise. The four topic came out on top:

   • Formatting and labeling
   • Lists and other enumerations
   • Source code in documentation
   • Images and diagrams
5. The group exercise (about 20-25 minutes)
6. Presenting each group’s exercise to the audience: Participants showed what worked well and what they found out. I shared my screen with the collaborative editor’s content, and the participants used their cursor plus voice/video to explain to the other participants what they did.

7. The closing questions (again on the whiteboard):

   • This excited me in today’s workshop …​
   • I’d love to learn more about …​
   • This is what I want to try next week …​
8. Finally, an open Q&A, where answered questions of the participants. I also showed how editing content in IntelliJ works, and that there are additional tools that help with writing and structuring content. Especially the build-in templates, that appear once you type ad- in an AsciiDoc document should help beginners.

How it went

First event at JUG Passau

For the meetup at the JUG Passau, I chose Microsoft Teams for people to share audio and video. As with Microsoft Teams participants can’t switch break out rooms by themselves, I set up several rooms. As only a member of the organization could start them, me or someone from the organization needed to be present in each room to start the meeting. Still, it worked well. The participants opened their microphones and sometimes also their camera, and engaged.

Some started with one group exercise, and then moved on to other exercises, so I think the 20 minutes were ok. Participants helped each other, and were happy to present their work in the forum afterwards.

Participants worked with the whiteboard interactively, and the closing questions gave a wonderful insight how they felt about the workshop and what they found useful.

In total, the workshop took about 90 minutes.

Second event at DevConf.US

Some months later, I gave the same workshop at another conference. I didn’t have a whiteboard like MetroRetro (as I wanted to have fewer tools participants would need to handle), the group turned out to be smaller (about 8 people), and I used the Hopin conference tools and Zoom instead of Microsoft Teams. Zoom would have allowed participants to switch break-out rooms themselves (although this time I missed to check right box for that). The time box for the whole workshop was 60 minutes, and I thought this would suffice.

Instead of using a whiteboard, I tried to collect the previous experience with Markdown in the Hopin chat. This was less interactive, and although I sent a note to the participants earlier, it took a while for them to respond.

Switching over to Zoom revealed that fewer participants than before had a quiet room and headphones, so that the audio quality was limited and communication suffered compared to the first workshop. As I didn’t use a whiteboard to collect previous experiences and as there wasn’t any voting on the different topics, I didn’t have a pre-selection and participants struggled for a moment to choose the right topic. Given the fact that we were a small group we went all to the first room, including me as the trainer. The participants were still engaged — given their level of audio/video capabilities. As I was in the room, the participants weren’t required to help each other, which made the training less intense. To make it a real training-from-the-back-of-the-room experience, I’ll avoid it next time.

In the end not using a whiteboard, and being only one group helped to cut some corners and allowed to keep the 60 minutes time frame. Keeping these elements and adding 30 minutes to the slot would have improved the outcome a lot, so I’ll not go for a 60 minutes training again.

Plans for the future

Participants were engaged in both workshops, so I consider both workshops a success.

Looking forward to other trainings, I’ll keep the whiteboard. I’ll also time it for 90-120 minutes, as all steps I had at the JUG Passau are important for a successful event and to fulfil the 4Cs of Connections, Concepts, Concrete Practice and Conclusions. I also want to show participants how writing in a real IDE like IntelliJ works. This almost fell short in the second workshop, and I don’t want participants to take the minimal Anita editor for real world use cases as an IDE has so much more to offer.

Restricting the number of rooms to match the participants is something I’ll do for the next workshop again, even if it requires another tool (the whiteboard) and another kind of interaction (the voting). And once the participants join a room, I’ll have them work on the exercise for a while without me, to get the interaction starting.

Do you want to have a workshop about AsciiDoc or Antora at your company, conference, user group?
Get in contact and fix a date!

To learn more about “Training from the back of the Room”, buy the book and visit the book’s website with additional material (beware, the design of the website is a blast-from-the-past). There are virtual and real-life training classes listed on the website as well. The book got translated to German recently, that’s the one I read.