Welcome to 2023!

This is the first Technical Content Creation Series Episode of the year.

The Tech Content Creator Series is a monthly interview series where I chat with folks in various technical content creation roles (technical writers, documentation engineers, developer advocates, and what have you) about their careers. My hope is for their stories will impact, inspire, and motivate you.

This month, my guest was Damilola Oladele. As of the time of this interview, Damilola is currently an Outreachy intern at Wagtail where he functions in the capacity of a technical writer intern. In this episode, we discuss what it's like to be an outreachy intern. We also talked about how the Wagtail team leverages its open-source community to get actionable documentation feedback to continually improve its documentation.

Let’s dive in.

Me: Hi Damilola, it’s nice to meet you. So you’re currently an Outreachy technical writer intern with Wagtail, can you tell me what’s that like?

Damilola: As the name suggests, Wagtail CMS is a content management system built on the Django framework and can be used to manage all the content of a website. Instead of fiddling with a codebase every time you need to modify the content of a website, you can make changes via the interface provided by the CMS.

Wagtail CMS has two documentation categories: A user guide for the CMS users and non-technical people, and a Developer guide, which is for the developers who set up and customize the CMS to suit the needs of an organization. In my role as a Wagtail Outreachy intern, I'm primarily concerned with improving the user guide documentation.

Me: Let’s talk about Outreachy for a moment, because a lot of people are always trying to get into Outreachy. What was the application process like for you? What did you do differently to get in?

Damilola: Outreachy offers underrepresented people paid internships. In the initial application form, you must clearly explain how you are part of a minority or underrepresented group to be considered for the internship. The response you provide is very crucial, and for me, I narrated real experiences of the kind of bias I have encountered.

After the initial form-based application, shortlisted applicants enter the next phase which is the contribution stage. Shortlisted applicants will receive a list of potential open-source organizations/projects to contribute to based on their chosen track (UI/UX, technical writing, or programming). I applied to the technical writing track and got a list of open-source projects that needed technical writers.

After receiving the list of potential projects, you’re expected to pick one or more to contribute to. Personally, I’d recommend picking and sticking to one project to avoid diluting your efforts. I picked Wagtail CMS and opted to work on improving the user guide documentation.

The contribution phase lasts for a stipulated period, after which mentors choose the best-performing contributors (based on several criteria) to become official interns. I was chosen over about 40 other contributors for reasons best known to my mentors. I started out by making daily contributions in the form of grammatical corrections to the docs. After a while, my mentors asked me to move to the next stage. At this stage, I had to analyze the user guide documentation and identify flaws and ways to improve it, then draft a licensing policy, all of which I submitted. We were also required to write essays about our Outreachy experience every week of not more than 500 words. I think doing all these diligently gave me headway.

Me: I made a tweet asking about ways to obtain actionable documentation feedback. You replied, stating that Wagtail includes a feedback box on each documentation page. You also stated that this approach has yielded valuable insights, the most recent of which was a suggestion to rename a section from browser issues to browser compatibility because the former had a negative connotation. Can you shed more light on how this feedback box is set up?

Damilola: The Wagtail user guide documentation is actually managed using Wagtail CMS; yeah we use our own technology. So, the feedback system is set up in such a way that any feedback is fed back into the CMS's admin interface. At the bottom of each documentation page, we have a rating box with two options: Is this page useful or not? If you select not helpful, you will be taken to a form where you can provide more information about why.

Me: How often is feedback reviewed and acted upon?

Damilola: Because Wagtail is an open-source organization, it is determined by the availability of our editorial volunteers. These editors are open-source volunteers who respond to feedback as soon as possible. One editor can post a piece of feedback in a Slack channel for others to consider and act on. I imagine that in a startup, tracking and resolving received feedback would be part of the documentation/content/devrel team's weekly routine.

Me: Aside from the feedback box on individual documentation pages, what other methods does Wagtail employ to obtain actionable documentation feedback.

Damilola: One advantage we have is our huge open-source community. Wagtail CMS is the most popular Python-based CMS, so, there’s a constant stream of people making suggestions of what they think can be improved upon and offering to help.

Another method by which we obtain actionable documentation feedback is through planned user surveys and interviews. Our approach is to start out by sending surveys to our entire open-source community. Then we identify recurring responses or patterns (if any), decide what should be paid attention to, and then reach out to some survey partakers for a possible one-on-one interview.

Me: What kind of questions are featured in this survey?

Damilola: In my time here, I've helped organize one user research. The primary goal of this research was to find ways to improve the user documentation guide; to learn what our users think of the documentation as a whole, to identify missing features, and to ensure that we are meeting the expectations of the majority of our users.

Some of the questions that were asked in the survey were:

• How do you use Wagtail CMS: Developer, Editor, Moderator, or Administrator. Seeing as we have different audiences/user categories, we wanted to make sure that we paid attention to only responses from non-technical users.
• How often do you use Wagtail CMS? The essence of this question was to make sure that we’re focused on people who use the CMS regularly and therefore have a deep familiarity with the product.
• How often do you use the docs? Same reason as above.

After our survey, we found that the people who have the most difficulty getting started with Wagtail CMS were new users. Then we conducted follow-up interviews with some users, asking questions such as:

• What do they think of the documentation as a whole?
• Have you used other CMS's? How does Wagtail CMS compare?
• How easy is it to work with Wagtail CMS when you’re using it side by side with the documentation?
• What features are not well documented?

Me: What were some challenges you encountered while carrying out this user research?

Damilola: Getting people to make out time for an interview can be tricky because people have busy schedules. One way we got a headset was to send out the survey to people within the organization who aren't developers but have a deep familiarity with the product. This helped us refine our questions and have something to start working with. So, you can start with the existing relationships you have, pending when what you want comes along.

Me: Final question. Assume the person reading this is a lone technical writer on a team looking to improve their overall documentation. Based on your experience, how would you advise them to approach this problem?

Damilola: I’d say start with using the docs yourself. Follow some how-to guides and see how easy it is for you. If it’s not easy for you, chances are it won't be easy for others.

The second step is to collaborate and develop strong relationships with, developers to discover if there are undocumented features.

Last but not least, stay in touch with your community, especially if you're an open-source organization. There may be people in your community who may have used your products in ways that even the core engineers had not considered. However, before throwing out questions to the community, ensure that you are not a novice and that you are familiar with the product so that you can ask relevant questions.

You can reach out to Damilola on Twitter, and read about his Outreachy experience here. Bye.