According to Hacker Rank 67% of developers have Computer Science degrees, roughly 74% said they were at least partially self-taught. Over 88% of respondents use Stack Overflow as knowledge-base on how to learn code. Youtube is the second most common (64%) and books is the third (60%) source of learning material. It is not a surprise that Millennials use YouTube (65%), while Gen Xers buy a book (85%). Without video content Millennials are probably not so interested about your product. Should your platform/API have video guides next to written guides depends of your target group.
English or something else?
Lingua franca in IT is English. End of story. There are possibly niche cases when targeting a specific language area when you might need to consider the option to choose otherwise. But still that is more of a choice only when you are doing more or less marketing purpose videos not get started guides or tutorials. That is by the way a good question what is the difference of getting started guide and tutorial. Some might think that getting started is referring to tutorials which are targeted at the early stage of onboarding. To me getting started, tutorial, quickstart guides are pretty much the same - they give the consumer advises and tips how to get certain thing done.
How long should the guide be?
Length is 2-10 minutes. Any shorter probably is just advertisement. Longer is likely not to be watched till the end.
What’s in the screen?
This can vary a lot. You might want to put face in the screen. It might be small in corner or just in the beginning. But consider the rather short length the face should not be there for more than a few seconds if even that. The narrator is no the topic, but the API or platform/feature. Thus most of the video should focus on the actual subject. Then your guide might be CLI driven (console) or it might be GUI driven. Depends on the case, needs and life cycle phase of the product.
Lets take an example Platform of Trust guides to bring some concrete in this post. We are developing the platform with API -first strategy. It also means that we have APIs ready and GUIs come sometimes a lot later. Naturally the GUIs use same APIs as we offer for platform consumers. Our initial guides are for that reason CLI driven. We have simple console (with brand colors) and then simple operations are shown in code level.
What about production of the guides?
We have written guides for the same operations too. Those are created first and video guides shortly after. Our own staff records a video (4K) in which they go through the guide and explain what is done and what is in the screen. Then external partner does the narrative and adds intro and outro. They have native English speaking people with nice clear voice. We upload the video guides to Youtube and embed in the beginning of written guide.
Keep in mind that video guides are rather fixed. You can’t easily update it just like you can with the written guides. This means that your product/API/platform should be pretty ready before video production. It is also good idea to add a notice next to the video that some parts of the commands used might have changed and the latest is always available in written guides.
If want to be bold and experiment, try online text to speech services. The quality is better than I anticipated, but still far from real person. Amazon Polly is pretty simple to use and it supports SSML. It enables more detailed control of the voice and tone. In my opinion that is not optimal for video guides if you want to have top quality. The early posts of this series are converted to speech with Polly and link to mp3 files is provided in the frontpage listing. Here’s a sample (text) and mp3.
I have to admit that I did not put much effort in testing the SSML. It might be possible to get pretty good result from it with proper use of SSML tags. I would assume that there are services which can already create pretty convincing narration without human intervention. If not, there will be.
What about voice?
Since the visual cues of attractiveness, reliability and appeal are practically lacking, voice of the narrator is crucial. Voice is a powerful media anyway. According to research we have sense for example emotional states from the voice as well as race, sex, age, even weight. Since the voice is so important in videos, I decided to take a deeper dive in to the subject. Probably deeper than necessary. I did some background research on voice and empathy as well as other elements such as vocal attractiveness which raises the attention towards sound/speech. I skimmed about a dozen articles.
Without any research it’s clear that narrator voice must be clear, pronunciation perfect or near perfect. That is just logical. Picking just one of your own staff to act as narrator might not be the best option. We are not the kind of persons who have “radio voice”. None of us is native English speaker either. I wouldn’t want to listen bad English pronouciation while learning something or trying to get a grip of a complex concept like a platform and how it works. Your staff might be excellent speakers at events or experts on the product, but rarely they have the optimal voice.
We required the subcontractor to find female narrator for us. Why? It would sound good to say that we want to promote women in tech. We do, but that is not the reaso. We strongly believe that empathy should be present in the guides and you can hear from the voice if a person is empathetic towards the listeners. According to research women are by far more empathetic than men. Of course there are women without much empathy but we are confident that our subcontractor can filter out psychopaths.
The aim is to get the listener hooked! Of cource the content matters, but how it is “laid out” is as important. Since this is human science, soft science, it’s not a surprise that results of various studies were somewhat conflicting. Low pitched male voice is often assosiated with confidence and leadership. We don’t want leadership in guides, we want empathy and feeling that we are helping the listener. Low-pitched voice is also said to sound dominant. Guide isn’t about convincing or dominating anyone. For that male voice might work better. Guides are 99% watched by people who are already convinced since they have decided to invest their time in the guide.
I found one interesting research by Babel et al which compared the attractiveness of male and female voices. The results indicated that while ratings by both sexes were highly correlated, males generally rated fellow males as less attractive than females did, but both females and males had similar ratings of female voices. Results suggest that female voice is less risky to be rated low or differently by sexes.
The study by Collins and Missing showed that men found high-pitched female voices more attractive. According to Jones et al women also show a preference for high-pitched female voices.
A recent study by Helfrich and Weidenbecher associating voice pitch with the retention of content in long term memory found that both high and low pitched voices led tobetter results than medium-pitched voices.
So does it really matter is it male of female narrator? I don’t know, history will tell us. Continue discussion in Twitter:
Some more to read from 100 Days DX
- #100 - The biggest open resource on Developer eXperience so far
- #99 - Hackers - the top 1% of engineers
- #98 - Invalid Open API spec files ruins the developer experience
- #97 - Lightweight API evaluation framework
- #96 - Embracing open source community driven tools development
- #95 - Exploring the multilevel nature of API Design Guides
While you are here...
Check out Platform of Trust in which I've worked to enable best possible developer experience!