Rapid and collaborative content creation through docathons

Docathons enable teams to collaborate and create as much content as possible in a short space of time. This activity became popular in the late 2010s in open source projects to enable rapid contribution from the development community. I first heard of a docathon at the Write the Docs conference in Prague in 2016. The docathon was one of the most well-attended events in the 3-day conference,

Docathons are similar to hackathons but for building content exclusively. You can have a hackathon where you write documentation or produce videos, but the emphasis of a hackathon is producing code for an app or a solution. As it is all about content, technical writers are of course best-placed to make a docathon a success in any software development company.

Here a few tips you can follow when planning and executing a docathon.

Establish the goals of a docathon

You first need to establish the goal of the docathon, taking in to consideration on what is achievable. For example, rather than writing pages for an entire site, the goal can be to create new pages for a small set of features, or just for a domain. Alternatively, you can use a docathon to build a small documentation site within the proposed timescales if it’s feasible. Bear in mind that is easy to get in to the trap of choosing a set of goals that are overambitious or difficult to attain. If you don’t set realistic goals, you may end up with numerous unfinished pages, which can be difficult to revisit at a later date.

When deciding the goals, consider whether or not the goals fit in with department objectives. For example, there may be a quarterly objective to revamp an entire section of the documentation, which may require considerable work. You could set a docathon target to revamp 1/3 of the site section, giving you the opportunity to achieve a sizeable a chunk of the objectives from a 2 or 3 day docathon event.

Create tickets

Work tickets (e.g. through JIRA) are important as they enable teams, both directly and indirectly involved, to track the docathon activities. When assessing the success of a docathon, management can refer to the tickets and various statistics on pages that have been completed. You should create tickets that cover all writing activities in a docathon, which link to larger work initiatives (e.g. epics in JIRA).

Decide on docathon participants

Your docathon participants write the content during the event, and need to be available on the days of the docathon Your key participants should be developers or product managers that have knowledge of the subjects covered by the docathon. However, be aware of selecting too many participants as coordinating tasks can be difficult. You should, of course, have at least one member of the technical writing team to coordinate activities, as well as edit, proofread, and publish the relevant pages.

Create templates

Templates ensure that teams can quickly create content in a uniform look-and-feel. Participants can create content quickly by using templates to “fill in the blanks” with the relevant subject detail. Although templates are never completely set in stone as writers are constantly refining them, you should ensure that there are versions that are ready for use on docathon day.

Prepare a style guide

It is important that participants can refer to a style guide. This ensures that they describe the content as consistently as possible. If participants feel that they are too pushed for time to refer to your style guide, create a crib sheet or style guide summary to help them. Even consider creating an interactive style guide to promote engagement.

Provide an example of a good page

Giving participants an example page that meets the standards can help them get started and in to the “writing zone”. Referring to a well-written page can ease participants from procrastination, which we are all prone to (writers and non-writers alike).

Ensure that the event is office-based

Many of us work and interact with others remotely from our home computers. However, it may be more feasible to hold a docathon from the office where participants are a desk away. In our post-Pandemic world, time spent working and participating in group activities in the office is crucial for breaking down silos and fostering a team spirit. A docathon also provides the perfect excuse for being in the office without attending meetings.

Decide on publication procedures

Towards the end of the docathon, you may want to publish the work so that your external clients can view the content. This is where you and your team can do the necessary magic, such as running deployment jobs on the new content. Publication procedures can vary depending on the toolchains you are using. If your documentation is closely coupled with Docs-As-Code, you may need to perform deployments in your pipelines, such as through running Jenkins jobs. However, if you are using a cloud-based CMS, like ReadMe, you just need to publish the content to Live from a Staging version.

Alternatively, you might choose to keep your docathon content in draft form and wait until the next documentation or software release for publication.

Food, drinks and prizes

Your content creators are going to have a busy day at the office on the docathon days. You may want to supply lunch to keep your participants going. When the docathon ends towards Close Of Business, you may want to reward them with food and/or drink. Prizes bring in an element of gamification to the event. You may also want to include a leaderboard to incentivise your team members. Keep in mind you may not want to make the docathon too competitive. The important thing is to produce high-quality pages in the allocated time. Excessive use of gamification might detract you from the main objective: content production.

Conclusion

A docathon is a good way to get your team together to produce documentation as there is almost always an element of fun. Technical writers can help immensely in facilitating, editing, and publishing the content. I’ve enjoyed helping out in docathons in the past as it has helped me exercise both document management and writing skills.

However, I also feel that there is a slight element of misconception about docathons. A docathon should not be about an individual’s task to produce the most pages. It should be a team effort to reduce the documentation backlog with the emphasis on producing quality over quantity. The activity is also as much an exercise in coordinating activities as it is in producing the content on the day. It is also vital to be able to resume your tasks from a docathon at a later date.

If you feel that your writing team and the wider contributors are uncertain and delaying in providing content, the answer may lie in kickstarting content production through a docathon.

Contributing through API design reviews

An API design review allows technical writers to join forces with product managers, business analysts, and developers in designing and building an API. This a truly collaborative way of designing and developing an API. Where I work, a design review consists of an off-site zoom meeting to discuss the requirements, technical considerations, and the documentation of a REST API in its design phase. These meetings fit in nicely with the collaborative ethos of the Open API specification, which includes tools like the Swagger editor. But how do we, the technical writers, contribute to the design and building of an API?

Collaborative API design with multiple stakeholders

How the design review session works

The key stakeholders of product managers, business analysts, developers, and technical writers aim to cover the entire design of an API in one or more review sessions. Each meeting is moderated by the development manager who also contributes to the design. In the meeting, the stakeholders cover the overview descriptions, headers, request and response parameters, error messages and schema elements of an API. The participants are fairly familiar with Swagger and the format of an Open API spec.

Agenda of an API design review meeting

An API design review usually covers the following agenda:

1. The product manager responsible for the API provides a business and technical overview.
2. There is a brief Q+A session to ensure that all participants have a basic understanding of the API.
3. The development manager steers the discussion to the API descriptions. This is where we offer suggestions for improvement.
4. Participants discuss other aspects of the API endpoints including the schema and the error message descriptions. This also provides an opportunity for the author to make further enhancements to the words.

Improving the API descriptions

We suggest wording for the summary and the description fields of the API endpoints in review. The summary field in an Open API spec is important as this is the first bit of text that a user notices when they see an endpoint in an API reference. In this example, the summary field value is “Add a new pet to the store”.

"/pet":{
         "post":{
            "tags":[
               "pet"
            ],
            "summary":"Add a new pet to the store",
            "description: "Add a new pet to the store. This must be from             
             a licensed breeder".
            "operationId":"addPet",

summary and description fields

The description field includes more details about an endpoint. Describing an endpoint is not easy if it is complex, and where different stakeholders have questions. For example, imagine a new POST endpoint in an eCommerce API that allows you to create discounts on a purchase. The product manager states that the endpoint is geared to discounts but does not provide any initial context on what the discounts are based on. Example follow up questions may include: “Are the discounts based on shipping/order volumes?” Without an in-depth and accurate explanation or clarification during the session, the technical author cannot improve the text.

Parameter descriptions

The Open API spec allows you to include a description field to any relevant parameter of an endpoint. One area we often check is where the description field for parameters are missing. It is important that any parameter requiring an explanation is associated with a description field, as developers rely on information of these parameters. The example below shows the description field to explain the status parameter.

"status":{
     "type":"string",
     "description":"pet status in the store",
     "enum":[
           "available",
            "pending",
            "sold"

description field for a parameter

Missing Examples

Each parameter must have an example. We know that developers love examples. Similar to the description field examples can help them boost their understanding of a particular parameter. The following shows a very simple example for the name parameter.

"name":{
         "type":"string",
         "example":"doggie"

example field

operationId

Each operation (GET, PUT, PATCH, or DELETE method) must be identified by an operationId. This ID can be used by code generators in other development environments for naming methods. An operationId that is understandable and entered in a logical and consistent matter can help developers. If an endpoint has versions, you can decide whether to include a version number. In this example, updatePet is a sensible name for a PUT endpoint for updating an existing pet.

"put":{
     "tags":[
         "pet"
 ],
"summary":"Update an existing pet",
"description":"",
"operationId":"updatePet",
"consumes":[
          "application/json",
          "application/xml"
],

operationId example

Reviewing pull requests

During an API design review session participants can review pull requests that contain the new or updated endpoints in the Open API spec. Pull requests are usually created by the development team and are associated with a JIRA ticket. Reviewing pull requests in the session is good because it ensures that specific review tasks are completed. Although some pull requests contain purely development changes, many require updates to the text and therefore our input.

It is worth noting that previewing the API endpoints in a Swagger interface is very handy for pull requests. Where we work, we’ve incorporated a Swagger interface with our Git-based code repository system (Bitbucket).

Improving overall design

In summary, the API design review allows us to work with other stakeholders using the interactive capabilities of zoom to improve the API documentation. The review allow us writers to get involved in the development and the definition of an API earlier in the development process. This ensures that APIs are released to a better level of quality. It also ensures that we correctly document endpoints with more complex functionality where its features may require discussion. I would highly recommend suggesting these sessions to a development manager if they do not exist already!

Picturing the end user

Writing documentation all begins from picturing the end-user and what they may want from your content. This is where creativity can play a part in the documentation process.

Recently, I’ve been working on a set of guides based on a UI. These type of guides had not existed before on our largely API reference-based docs site. The new guides provide a good challenge in tailoring the documentation for a target audience.

Making a start

Starting on a clean slate always means that there are many unanswered questions. Do you provide a complete set of step-by-step instructions? Do you include videos? Do you provide a sales pitch? How do you present example scenarios? To avoid procrastination, the temptation is always to dive in to the details before planning the content. The obvious questions are the whats, instead of the sometimes more crucial whys and hows.

Defining the audience

We must ask the question of who is the primary and the secondary audience to find what they want from the documentation. Through experience, I’ve found that the more information you can provide at the planning stage about the target user, the less work you have to do later. So if you know that the primary user is a developer, you would complete your definition with answers to the following questions.

1. What are their job titles?
2. What tasks do they perform?
3. What levels of knowledge do they have on the product?
4. How do they use the product?
5. What could we know about the background, level of education, age, IT experience, English proficiency?
6. In what situations to they use the product that you are writing about?
7. What is their work environment like?

Applying the definition

Once you’ve defined the audience or the persona of the guide, how do you do then apply this definition to your documentation? This is an area I feel is often overlooked. But here is how you could go about this.

Taxonomy

The taxonomy applies to your new guides, however big or small. It may not be the same as the taxonomy of your documentation site. For example, if the audience is likely to be developers, you may want to present reference material that is organised alphabetically or chronologically. If the audience is less technical, you might want a set-by-step instructions organised by function, from basic steps to advanced steps.

Headings

The type of headings may also be derived from your definition. If your audience are less technical and have less assumed knowledge, you may want to us headings such as “Fundamentals”, the “Basics” or “Getting to Know”. If you know for sure that the audience is less technical, you can use these words with more liberty. However, err on the side of caution if the audience are more advanced users. There is an argument to avoid words like “basic” or “simple” (watch Jim Fisher’s presentation on Don’t say simply).

Documentation structure

Good documentation structure is key. Deciding on the flow can actually be one of the most challenging parts of designing a document. Would you design the content so that novices follow the sections and pages from start to finish? Or will you design the content so that advanced users can go straight to the content they need?

Visuals

Visuals are a powerful way of communication in technical docs. However, there are 2 things to bear in mind: 1) There is no point in creating visuals if the concepts can be described in words. 2) Not everyone is visual, some readers “think more in words”.

Visuals are effective for overview information where you are communicating the big picture to a less technical audience. But they maybe less suited to programmers, where a visual representation might show a concept that is painfully obvious.

Terminology definitions

Your audience analysis can also determine your approach to terminology definitions. If the audience is likely to be new to your technology, they may want to know what the terms mean that might be specific to the technology or the industry. For these users, ensure that you define Acronyms and link to a glossary section. While for more advanced users, you can skip definitions and focus on describing the technical content accurately. Never assume that the audience knows what the terms mean; it’s best to do the analysis before writing the content.

Considering your style guide

Style guide guides are great for defining the style of writing for your pages as a whole. The audience definition can easily be incorporated in to your style guide. To help your users start writing, you can include boilerplate examples where needed.

In short

Audience analysis doesn’t just end with a high level definition. It requires you to follow through the current or proposed document design, looking at the different elements of your document. There is another added value of creating boilerplates, which is your Agile or CI/CD framework. The next step may be to incorporate your style guide or template with AI – a topic perhaps for another blogpost. Until then!

Managing versions in ReadMe

ReadMe has a very intuitive GUI interface for hosting API documentation. With ReadMe, version management is radically different and much simpler than a static-site generator solution. For example, there is no need to perform commits and merges.

What is ReadMe?

Readme includes a markdown editor that allows you to create compelling documentation on APIs of various types, namely API reference, guides, changelog, and recipes. Some of these capabilities described here are for their enterprise version.

The separation of the documentation types provides individual benefits. For example in the API reference section, you can easily incorporate Open API specs that originatein repositories like SwaggerHub or Bitbucket. For the guides, writers and contributors can directly contribute, and there is no need to resort to source control through git. I will describe the version management capabilities for it’s guides.

Showing File Version History in a GUI

For producing guides and your colleagues can work together on the same ReadMe file. Any updates made by you and your colleagues are logged in a version history of the file. This makes it ideal for collaborative working. And whenever you need to revert to a previous version, you can easily do so through the interface.

ReadMe’s Staging Environment

ReadMe’s staging environment (on the enterprise version) is where all you do all your work on your files. You can then deploy those changes to production. Before deployment, changes that you add are not visible.

This all sounds simple. But in an Agile workflow, there may be some pages you want to publish whereas you may want to hide other content that is not ready. You can set a page in progress to Unpublished, and then when you ready to publish change it’s status to Published on deployment.

When you set a page to unpublished, it is greyed out in the navigation. This allows you and other collaborators on the documentation project to easily identify the page as unpublished. You can also rename the page and add tags, e.g. “To be released”. Having a naming convention can also be helpful. To make a page visible when deployed to Live, you set the page to the page to be Published to staging. Read more in Publishing content with staging.

ReadMe Versions

You can manage different ReadMe versions for your platform release cycles. For example, if there is version 3.1 of your API platform due to be released, you can publish version 3.1 of the documentation in staging; once released you can deploy the staging version of 3.1 to Live. You can then upgrade your staging version 3.2, and deploy 3.2 to Live for the next release. However, you can also update lower staging versions, for example, when a change needs to be patched.

Suggested Edits and Version Control

Suggested edits provide a convenient way for contributors to add content to a ReadMe page. Any reader of a page can make a suggested edit. If you want to include the suggestion, you can accept it and merge the content to your most recent page version. Suggested edits are particular handy for managing page edits, especially if you want to avoid too many content collaborators making changes at once.

Tracking Changes

You can track changes at both the page and project level. For each page, the version history lets you find out who updated the page and when. While to track any page update in your ReadMe project made by any of your project users, you can refer to the audit logs. You can easily filter the audit log to pinpoint the exact edits. For example, you can select a Readme “Member” (or user) by their email address and find out all their edits and page views.

Conclusion

The simplicity of it’s version management makes it ideal for you and multiple collaborators to start writing quickly. This also allows a technical writing team to oversee changes and develop flexible and effective editing processes. It’s worth noting that Readme constantly build release new features, and future versions may allow more collaborative workflows on guide content similar to git.

Using Confluence for tracking work

As technical writers we can get involved in almost everything in IT. One area that is essential, and has become increasingly important, is project management. Confluence is effective as a communication tool in project management and tracking work. Even though the tool itself is an enterprise wiki and not designed to be a project management application, it has simple features to make life easier when tracking work.

Why Confluence is good for communicating project plans?

Where I’ve worked at in recent years, we used Confluence for our internal documentation. Developers, rather than technical writers, would often write pages to describe an area of functionality before it gets added to customer-facing documentation. When Confluence becomes an internal “go-to” documentation, we can also use it for planning and tracking.

In Agile, we’ve become dependent on tools like JIRA for planning, managing, and tracking projects. In JIRA, we create tickets that are used in epics and stories. Epics hold the different stories that are used for an area of work. However, JIRA doesn’t effectively show all your work in a visually friendly way. You are restricted to the views as provided by the boards. There needs to be a way of showing work to different participants in a project and allow them to collaborate. Also, entering details and filtering comments in JIRA tickets is not always an effective strategy. This is where Confluence comes in to play.

Example scenario

You might be working collaboratively on documentation with another development team to revamp their existing content. This may consist of many pages that need to be in client-friendly format. Here is an example of a Confluence table that you may want to include for a fictitious traffic dashboard solution that takes place across sprints where different developers create internal documentation that gets used in the portal. Notice that the comments allow different participants to interact as they and the writer work on several features of the traffic dashboard product.

What the table consists of

Tickets and relevant sprint dates can be added to the table – you can add cell background colouring for visual impact. There would be a link to the page in which you or the development team has worked on, and a link to the internal page. Very importantly, there would have to be a comment entry as tickets and work is likely to change. There may be other columns that can be added to the table, e.g., the associated epic. Also, Confluence has a set of project management templates, which you can make use of too.

Keeping visibility of the Confluence page

It is easy to lose visibility of a Confluence page, especially if the taxonomy and organisation within Confluence is confusing. Confluence allows teams to create content, but curating pages can become an afterthought. When another team is working with a technical writing group on a set of pages, we rely on them to refer to that particular page. Updating a duplicate page in another space defeats the purpose. However, it is easy to forget a link to a page, and it can get lost until you search for it.

Adding the same Confluence page to slack channels, meeting bookings, and the ticket itself helps to remind people where they should go to in order to maintain the page.

Conclusion

I’ve been guilty of creating Confluence pages that outline an entire documentation project without aligning it to JIRA tickets. Confluence is particularly effective when project plans can’t be shown by itself through a sprint board. Tables provide a very happy medium of ensuring that the work is tightly linked with JIRA, while letting you choose the important information to communicate.