In my last post, I wrote about how designing an ‘open course‘ empowers others to make desired edits more easily. One major component of an open course is providing adequate and accurate documentation for your intended audience. If you were handed a course to teach or redesign, what aspects about the course would you like to know? Probably as much as possible, which would require a strong set of documentation detailing design processes and decisions, learning outcomes, tutorials for using novel course elements, and so on. If you care about having a solid set of documentation for your courses, then you may be a ‘Documentarian‘. In this post, I look into some components of good documentation design from the software field, and apply them to instructional design.

Informing the recommendations of this post are the Documentation Principles of Write the Docs, a “global community of people who care about documentation”. As described by the Write the Docs authors, their set of principles:

“seeks to define similar standards for software documentation that, when practiced, will foster clean and intuitive content”

https://www.writethedocs.org/guide/writing/docs-principles/#documentation-principles

While software is the stated primary purpose of these principles, much of it is applicable across a wider range of subjects, with aspects of instructional design (such as design and code choices) falling into similar categories.

Why is documentation important?

Every Instructional Designer will work with many different people, known as stakeholders, across every project. The stakeholders of a project fulfill different roles and have distinct requirements. Fellow Instructional Designers, eLearning Developers, Middle and Senior Managers, Subject Matter Experts, and the learners themselves are all examples of stakeholders with different needs and roles. Each of the stakeholders on any particular project will require a certain level of documentation matching their needs. Use of an external tool, for example warrants instructions for how to incorporate the tool into an LMS and its functions for designers, but also instructions on how to use the tool as a user for the learners on the course.

Perhaps some of the most important people to consider when designing a course are the ones who will inherit it later on when the original designers have moved onto other projects. Because of this inevitability, proper documentation is key to understanding how a course was designed, the original intended audience or needs analysis (in case any prerequisite courses are changed in a way that breaks the flow of this one – example: switching from one programming language to another in the classes leading up to this, resulting in it not being fit for purpose), decisions made and why they were taken, how certain features work, just to name a few.

With these reasons for well-structured documentation in mind, what should designers include in documentation? For that, Write the Docs has some advice.

General recommended documentation principles

Write the Docs breaks down “good documentation” into multiple components. The full explanation of each can be found on their Documentation Principles page. Here, I will just use the summary of each one from the page.

The components state:

Documentation should be:

Precursory

Begin documenting before you begin developing.

Participatory

In the documentation process, include everyone from developers to end users.

The content (meaning how documentation is written) should be:

Arid

Accept (some) Repetition In Documentation.

Skimmable

Structure content to help readers identify and skip over concepts which they already understand or see are not relevant to their immediate questions.

Exemplary

Include (some) examples and tutorials in content.

Consistent

Use consistent language and formatting in content.

Current

Consider incorrect documentation to be worse than missing documentation.

Sources (meaning where content creators store documentation) should be:

Nearby

Store sources as close as possible to the code which they document.

Unique

Eliminate content overlap between separate sources.

Each publication (meaning the end product that users see) should be:

Discoverable

Funnel users intuitively towards publications through all likely pathways.

Addressable

Provide addresses to readers which link directly to content at a granular level.

Cumulative

Content should be ordered to cover prerequisite concepts first.

Complete

Within each publication, cover concepts in-full, or not at all.

Beautiful

Visual style should be intentional and aesthetically pleasing.

A documentation body should be:

Comprehensive

Ensure that together, all the publications in the body of documentation can answer all questions the user is likely to have.

Documenting course designs

Taking the above principles, which were initially designed for software, as a guide, we can see how they would fit into the field of instructional design.

General ideas

The principles of documentation being precursory and participatory are simple to follow, especially if one takes on a project management role in course design. Intake meetings and early plans are the first steps to crafting course design documentation. It is at this stage that the initial course design plans are mapped out by the stakeholders on the project. This includes Designers, Faculty, Project Managers and Product Owners (if these are separate people), to name a few. The initial plans for learning outcomes, assessments, and general ideas for activities on a more granular scale can all be converted into documentation on the structure of the course. These would usually fit into a ‘Design Solution’ document that gives an overview of how higher level course decisions are put into practice, or at least intended to be, once the course is running. An ID and the rest of the course design team could revisit this documentation during an evaluative stage to see if things were still going to plan, or modify it based on feedback.

Intended learner journey

I use the phrase “learner journey” a lot, but I am not entirely sure how well known it is, nor if I am using it in a standard way. So for this instance, my meaning of “learner journey” is the following: How the course developer is expecting the learner(s) to interact with the course site. This includes things such as: what learners are expected to click on when reaching the course landing page, the order in which they are expected to complete modules, how assignments are completed, etc. There is room here for interpretation, but it does not hurt to note the intended learner interactions and progression through a course. That way, other faculty members who may be teaching the course in the future can quickly understand learner progression too. This could take the form of a more technical document for fellow instructors, and a quick video for students (or more, depending on how in-depth you wish to go in the learner-facing side of things).

As an Instructional Designer, I often take on the role of the learner sometime during a course development. I will set out a specific meeting time with a faculty member to go through how I would approach this content as a learner, and ask them if this was an intended way for the learners to interact with the content. I usually start by following the order of the module, which is usually set up in the order a learner should complete tasks. What happens, though, if a learner decides that they are just not going to bother reading the Overview page for that week (or any week) and skips right to the Assessments? Is there anything preventing the learner from completing an assignment before they know important background information? Maybe some sort of purpose statement would help (e.g. “This assignment will test your knowledge of learning materials for Week 3. You should complete this week’s background reading tasks before submitting your work.”)?

Content, or how documentation is written

Most Instructional Designers will know about how to make a page more readable by including headings, descriptive hyperlinks, and other stylized formatting like ample paragraph breaks and correctly set up list items (ordered and unordered, for example). If you can create documentation in this way, it meets the skimmable principle and helps readers quickly identify the section they are looking for. I would also recommend adding a unique ID to each distinct section of each page so readers can quickly jump to it using a navigation menu. To find out more about this, see the W3Schools HTML id Attribute page. Once these are set up, you can link anyone to a specific part of the page.

In the previous article on designing the open course, I included a section on the “Side by Side Code Block Tutorials” I use to demonstrate new and complex course elements. This aims to hit the exemplary principle, as it gives readers a quick example of how certain elements work and how to manipulate them in the future.

Video tutorials

Video tutorials are another way to give examples using a step by step process, and provide an additional level of personalization that is often missing from text-only tutorials. There are some downsides to video tutorials, however, which may influence the decision to create them.

Each of the following involve the time commitment required to create videos in the first place, and the principle of staying current.

1. Scripting and editing
   • Usually a video tutorial, or series of videos, involves scripting what the person giving the tutorial is going to say. With written documentation, this would usually be the end of the process – but with videos, it is only step one. The written form then needs to be spoken, correctly, and edited to make sure any mistakes are removed or audio synched up with what is happening on the screen.
2. Editing mistakes or changes
   • It advisable before creating a video tutorial to check if the procedure, process, or system is going to remain in place for long enough to make the time investment making a decent tutorial video worth it. It is a lot easier to change text-based tutorials when something changes than record another video. Additionally, videos are a more personalized version of a tutorial, and if the initial video creator moves on to another position or institution, it would no longer be possible to keep the consistency of any other videos in the documentation.

Those who write documentation with others will know about the importance of an agreed upon style guide. Using the same style of writing, formatting, and terminology across pages and writers ensures that no one section or page stands out or looks jarring in comparison to another, thus fulfilling the consistency principle.

Sources, or where content creators store documentation

For an Instructional Designer, it is not always possible to include documentation directly next to the thing it is explaining. For example, certain Learning Management Systems will remove code comments from all pages, leaving just the content. This is contrary to software development in general, where comments can be left inside code without issue. Therefore I recommend expanding the definition of ‘nearby’ when it comes to documentation for online courses to get around this potential problem.

How you, or your institution, store documentation will have a large effect on how people interact with it. Some institutions use specialized software such as the well-known Confluence by Atlassian, which allows collaboration between users. Other platforms such as Google Workspace are easier to start using for universities and colleges, which often already have Google accounts ready to go, and can be used without extra costs. A similar outcome is offered by other platforms such as a WordPress installation with multiple users creating and contributing to existing articles. Depending on the Learning Management System, it is possible to include documentation closer to the course files (such as attaching files to pages), which is recommended under the nearby principle. Using a single repository for documentation is important so that similar and identical information (such as tutorials on the same topic) are not unnecessarily duplicated (i.e. kept unique) in multiple places such as on an LMS, blog, shared docs. For example, a user of Canvas duplicating tutorial pages across courses leads to problems if part of the tutorial needs to change. This means numerous edits across multiple courses as opposed to pointing to one central location that requires edits only once.

Publications, or how someone can find what they are looking for

Continuing from the previous paragraph on Sources (where the writers store documents), the discoverability of the documentation is key. Where are faculty, designers, and support staff likely to look for help on various topics? Consider linking to the established repository where possible – rather than duplicating it across multiple sites. This will make it easier for others to find the help they require. In a previous section, I included a link to the W3Schools HTML id Attribute page. Specifically here, we are interested in the “HTML Bookmarks with ID and Links” section which tells us about how to jump to different “bookmarks” of a very long page. This is handy when you want to point someone directly to a smaller part of a more complicated and longer page. Doing this manually, however, can take a lot of time, but there are shortcuts for creating these IDs.

When writing documentation, I often use Markdown and then export to HTML. During this conversion process, the headings are automatically given a unique ID in HTML. When pointing people to this part of the documentation, I just need to append a # and the ID name of the heading to the end of the URL. This is known as making the documentation addressable, and links the reader directly to where they would be helped the most. For example, I might want you to go directly to the General recommended documentation principles section of this page, and you can do so with that previous link.

The Write the Docs authors ask the following question:

Can a reader follow your entire body of documentation, linearly, from start to finish without getting confused?

Answering “yes” to this would fulfill the requirements of being cumulative, and this is important when writing something like a tutorial for faculty from start to finish. I try to structure HTML tutorial documentation with the absolute basics first, using headings to structure the page, so that if an instructor already knows basic HTML/CSS principles, they can just skip to the sections that are important to them. If they know nothing about it, however, they should be able to start at the beginning and go through the steps in order.

Completeness of a document increases in complexity depending on what you are writing about. Rather than overpromising what will be in the documentation, state to the reader which parts are covered and stick to those. For example, if there are five assessment criteria for an essay titled Essay 1, only covering three of those in a document titled “Assessment Criteria for Essay 1, Explained” would be misleading.

The beauty of a page is subjective, but proper document structure can help enormously. Things like logical reading order of headings, use of whitespace, properly sized images with captions/alt-text go a long way to making documents more readable.

Documentation Body

The time required to make your institution’s documentation comprehensive also depends on the complexity of the systems in use. Write The Docs defines comprehensive documentation as being able to answer all the questions a user is likely to have. Instructional Designers are often connected to all aspects of the course, and can work with the various teams involved to provide the informative questions and answers required to be as comprehensive as possible for all stakeholders.

Conclusion

Creating successful documentation in the Instructional Design field starts from the inception of a project. It begins with the very first needs analysis and ends with a fully comprehensive set of publications that are easy to access by both writers and readers. It is a collaborative process and involves promotion and discoverability. but once created, it provides opportunities for learning, understanding, and importantly, modification and revisions to existing projects. For those thinking of designing an open course, or if you simply like learning more about how things work, perhaps you too are a Documentarian.

References

1. Chambers, P. (2022, May 23). Designing the open course: Why Instructional Designers should follow a “right to repair” plan. Ecampus Course Development & Training Inspire Blog. https://blogs.oregonstate.edu/inspire/2022/05/23/designing-the-open-course-why-instructional-designers-should-follow-a-right-to-repair-plan/.
2. HTML id Attribute. Retrieved from https://www.w3schools.com/htmL/html_id.asp.
3. Mundorff, M. (2022, April 18). An Introduction to Markdown. Ecampus Course Development & Training Inspire Blog. https://blogs.oregonstate.edu/inspire/2022/04/18/an-introduction-to-markdown/.
4. Write the Docs, CC BY-NC-SA 4.0.