Creating user documentation and online Help in a Continuous Integration/Continuous Delivery environment can be challenging for technical communicators and developers.
Last week, I spoke at, and attended, Madworld 2016, the conference hosted by MadCap Software for its users. Here is a summary of what I saw and heard on the second day. These were mostly for advanced users; I didn’t see any of the presentations aimed at new users of Flare.
Last week, I spoke at, and attended, Madworld 2016, the conference hosted by MadCap Software for its users. It’s the most rewarding and enjoyable of all the conferences on technical communication that I attend. Here is a summary of what I saw and heard on the first day.
Yesterday, I wrote:
“There are some activities that seem like they always could be improved. One is creating an authoring environment where professional technical communicators and other staff can work together.”
Writing online Help is different from writing some other types of content, in that it involves topic-based authoring. Content is stored in modular, re-usable and flexible chunks of information. By moving away from a page-centric, document model, you’re able to organise and present published information in many different ways. However, it’s a different approach to what many non-professional Technical Authors are used to. Unfamiliarity with this content model, as well as the tools, can make collaboration difficult.
There are some activities that seem like they always could be improved. One is creating an authoring environment where professional technical communicators and other staff can work together; the other is setting up the best lighting for training videos.
This is especially true for videos where chroma-key will be used to remove and replace what was behind the person being videoed. The type of background designed to be easy to be removed from a video is known as “green screen”, although sometimes the colour can actually be a shade of blue.
In the past, we’ve used a green screen cloth on a frame, which has worked fairly well. However, it was bulky. We’d either have to dismantle it and the reassemble it for each recording, or live with office space being taken up by the frame and cloth.
There also always seemed to be a few wrinkles in the cloth that resulted in a green halo around the presenter. Photographers call this “spill”, and it’s caused by light bouncing off the green screen on to the presenter. Many professional video software applications have a feature called spill suppression, but it’s best not to have to use it in the first place.
In the end, we decided to take a different approach and paint one of the office walls. Using a special latex green screen paint from Germany, we painted a large green rectangle. Here is a photo taken after the first two coats of paint:
It took quite a few coats to get an even colour, but it has made recording videos a lot easier, and it’s given us back some office space.
It’s reduced the amount of green fringing around the presenter, but there is still a little of that if someone looks closely. We may never be able to get rid of it completely, unless we carry out post-processing spill suppression. However, we believe we can make some improvement by changing the bulbs in the kicker lights.
This image from Virtualsetworks.com shows where the kicker light should be placed:
You can never have too many lights.
Hopefully, we’ll come up with even more improvements, and report on those in the future.
Anyone with children or teenagers will be aware of the popularity of video bloggers, or vloggers. Their videos on YouTube rack up thousands of hits, and there is even a magazine dedicated to the activity.
Many vloggers provide instructional information, such as makeup tips, so it should be no surprise that some have moved on to more technical subjects, such as Zoella’s guide to Swagger API, and Alfie’s hints’n’tips for Eclipse configuration.
Due to the high high fees they command, partnering with the most popular vloggers is only feasible for large organisations with big budgets, such as Apple, Google and IBM.
For smaller companies, the best option is to create a vlog using their own internal staff. To help those Technical Authors wanting to create a vlog for their content, you’ll find below links to some free background images you can use in your videos, to give that recorded-in-the-bedroom feel. Simply record your instructional video with a “green screen” background, and use the chroma-key feature in Camtasia or Captivate to replace it with one of the vlogging backgrounds below.
If you’d like to obtain the complete “technical communication vlog collection pack”, simply contact us via email.
- A researcher used Buzzfeed style headings on Help pages – the results will astound you
- Lars-Po Faydöl: The man you see in every Ikea installation guide
We welcome you comments
Please share your thoughts below.
Cherryleaf’s Ellis Pratt will be speaking at Lavacon’s first European conference. This will be held on 5-8 June, at the Trinity College Conference Centre, Dublin. Ellis’ presentation will be on the 7th June, and it’s called “Markdown – Friend or Foe?”
If you’re going, do say hello.
We’ve written our new training course on documenting APIs, bar the model answers, and it’s now out for review. We’ve learnt a few lessons, and confirmed a few beliefs, whilst developing the course. We thought we’d share them below:
- Start with the absolute basics. It’s best to assume little or no knowledge of the subject, and start from there. It’s easier to skip or omit those sections, than try to add them in at a later stage.
- Stick with a single theme for the exercises and examples. One of the challenges we had was to create exercises and examples that take delegates through all the stages of developing API documentation. We decided to base these on an imaginary API for a hospital, and this turned out to be a good choice. It’s meant we can use real world examples from healthcare, as well as ones we’ve created, during the course.
- Make the examples visceral. The more you can anchor the exercises into people’s lives and experiences, the more real and meaningful they will be for them.
- Don’t get sucked into looking at only one tool. There are a number of ways to develop API documentation, and the tools are developing at a rapid pace.
- Don’t be too ambitious with the exercises.
- Writers want to write on a training course about documentation, so give them the opportunity to do so.
- Set realistic expectations regarding coding skills. You can’t teach people how to code in multiple languages in a day, so you need to provide building blocks that they can build upon in the future.
The slide deck now comprises 330 slides, and the test recordings indicate it’s a one day course. We’re still not convinced we have the best title for the course – if you have any suggestions, do let us know.