Technical Documentation Writing Principles

This internal document describes stakeholder requirements and derived writing guidelines for each technical documentation type used within Learnosity's communication strategy.

Cameron's Cover

When working at Learnosity, I co-authored this writing guide. Learnosity is a tech company that empowers education providers to build a breadth of assessment questions within a web page, run it at scale, and analyse results. The challenge for us technical writers was to explain the powerful technology clearly, concisely and intuitively to a broad range of stakeholders. When talking with others I’ve discovered that there are many tech companies facing similar documentation challenges. Learnosity has kindly allowed me to share this internal document to help others craft something similar. This version has been lightly edited to remove some Learnosity specific information and help readability for an external audience.

Positioning document types - today

Positioning document types - tomorrow

Key Messages to convey

• Learnosity EdTech technology is world-leading.
• Learnosity technology provides value for money.
• Learnosity people are technical experts.
• Learnosity and its people are trustworthy:
• Trustworthiness = Credible * Reliable * Open * Intimate / Self Interest.
• We provide convincing reasons for why Learnosity products, services, and value are superior.
• We have a long track record of delivering.
• Trusted organisations have selected us, recommend us after doing their due diligence.
• Someone I trust has recommended Learnosity.

Writing principles

• “Every page is page one”. Assume someone could have reached this page as a first page from google. Make sure there is sufficient navigation to orient yourself within the page.
• Set the stage sufficiently so that the reader understands the purpose of this document, what they will gain from it and any assumed knowledge they will require.
• Use hyperlinks to reference terms and other pages.
• Write timelessly, so your content is still meaningful in a year or two. Avoid terms like “new feature” which is relative to the time it was written. (Release notes can and should be time-specific, as they are related to a point in time).
• Respect the reader's time. Write clearly and concisely.
• Use hyperlinks to reference terms and other pages.

Quality Control:

• Check for typos and that the instructions make sense.
• Ensure formatting is consistent throughout the demo.
• Ensure that the images are compressed and of an appropriate size.
• Images should be crisp and royalty-free.
• Check for unnecessary scrolling - both horizontal and vertical.
• Check that the content fits well into target screen sizes, i.e. nothing crucial is cut off. This is particularly relevant for graphs and charts.

Publishing principles

• No broken URL links or broken HTML, or broken demos. (We should check this automatically.)
• Examples should be available to be cut-and-pasted in the user's preferred programming language. (Ideally write a conversion script to automatically convert a server-side PHP to JSP, .net, etc.)

Exemplar Examples

We need to make use of example content which:

• Is universally understandable.
• Is timeless and doesn’t need to be updated.
• Where possible, is simple enough for the reader to know answers to questions.
• Is professionally constructed, and has content which is recognisably of high quality to an educational professional.
• Demonstrates the power of the feature being demonstrated.
• Ideally is applicable across multiple domains.

Universal topics include:

• Science
• Weather
• Animals
• Colours
• Chemistry
• Anatomy
• Solar System
• Maths
• Food groups
• Categorise fruit, vegetables, serials, protein
• Healthy food categorisation
• Food with allergies
• Health
• Body parts
• First aid
• Safety

Topics which are not universal are:

• Geography (People are likely to only know about Cities close to where they live)
• History (as history is usually tied to Geography or a specific culture or a time period)
• Pop culture, or news items, as they become dated.
• Questions using regional units, such as money or miles/kilometres
• Culturally sensitive questions, such as based on religion.

Blooms Taxonomy Teacher Planning Kit is useful for constructing questions.

Document Types

Solutions

Description:
The aim of a Solutions page is to help the reader imagine how their domain-specific problems can be solved using Learnosity functionality. It is about describing and showing Learnosity features using use cases and terminology familiar to the reader's domain.
Length: 2 to 4 pages, including diagrams.
Target Persona(s):

1. Non-technical, business savvy Product Owner who is unfamiliar with Learnosity.
2. C-level decision maker.

User Stories:

1. As a Product Owner, I want to understand that my business domain challenges can easily be solved with Learnosity functionality.

Doc Structure:

• Title: Describe how Learnosity can be used to address a specific domain.
• Introduction:
• 1 to 2 paragraphs: Discuss the domain, and how it is possible to solve challenges in this domain.
• Probably start with a sentence defining the domain - so that the reader and author both understand each other's domain definition.
• Ideally, mention key business requirements associated with learning in this domain - maybe legal regulations, implications of not being trained, specific learning challenges relevant to this domain (such as requiring complex mathematical script).
• Focus on the “Why” and “How” in this top part rather than “What”. I.e. we probably don’t mention Learnosity yet.
• Multiple sections of Domain-specific concepts/challenges
• Heading
• Include a hero image
• 1 to 2 paragraphs: Discuss how Learnosity addresses an important challenge within this domain.
• Ideally include a “Find out more” link, which points to a Learnosity page, ideally a Features page, or maybe an example of this feature in action.
• Example:
• More info:
• Provide links to relevant Learnosity documentation (Typically point to concept descriptions within Guides/Knowledge Bases, Case Studies, Demos, maybe Features, probably not Reference pages.)

Demos

Description:
Seeing a working demo is often the easiest way to visualise how a feature could be used, and gain confidence that it can be implemented.
Target Persona(s):

1. Non-technical, business savvy Product Owner.
2. C-level decision maker.
3. Product owner, trusted author, or trusted developer.

Demo Guidelines:
When creating interactive assessment examples it should be the best representation of our tools and functionality. We want viewers to be impressed! Consider:

• Is the content applicable to the particular domain of the solution?
• Does content follow our exemplar guidelines?
• Does the content showcase a variety of levels/standards?
• Does the content include a wide variety of question types?
• Would imagery and/or videos help make the content look more appealing?
• Consider using various layout options e.g. split-screen, paginated passages, tabbed passages etc. as appropriate.
• Are all the features listed on the Solutions page incorporated into a demo?
• Demos should provide a compelling experience on mobile and non-mobile screens, i.e. on smaller screens from 768px wide and up. In some instances it may be appropriate to create two demos - one for mobile and one for desktop.

Quality:

• Demos should have quality criteria, such as auto testing, with designated Learnosity maintainer.
• Demos are likely to break when software is updated. Testing demos should become part of the software release process.
• Demos probably should have a matching tutorial, and tutorials probably should have a matching demo.

Case Study

Description:
Provide a clear, concise, high level, compelling overview of how an organisation has implemented a Learnosity based solution to solve a specific problem (or problem set). The problem might be about increasing efficiencies, reducing costs, attracting sales, adding features, or solving a technical challenge. Our aim is to use domain-specific language to help the reader realise that Learnosity has experience addressing their specific use case successfully with other companies that they know and trust, and then forward the reader to the relevant Learnosity solutions/features pages.
The reader will typically reach this Case Study on recommendation of a Learnosity salesperson, or after reading a Learnosity Solutions page.
Length: Ideally limit to two to three pages, including diagram(s). More complex use cases can be longer, but be aware that “less words get read more”.
Target Persona(s):

1. Non-technical, business savvy Product Owner who is unfamiliar with Learnosity.
2. C-level decision-maker.

User Stories:

1. As a Product Owner, I want to confirm that Learnosity has been used to implement something similar to what I want to achieve.
2. As a Product Owner, I want to confirm that the implementation was successful, and within expectations of time/effort.
3. As a Product Owner, I want to confirm that the implementation was from an organisation I trust - typically in a related industry.
4. As a Product Owner, I want to be reassured that Learnosity is a company that I should be comfortable doing business with culturally; that they understand my problems and are here to help.
5. As the Company in the case study, I want it to speak favourably of me such that I might reference the case study in my marketing pipeline.

Doc Structure:

• Title:
• The title should describe a concept that we are explaining. It should be short and to the point. Up to ~ 5 words.
• In pull text font, describe the value of this case study in one sentence.
• About
• Put this into a right sidebar (or at the bottom for smaller screens)
• Introduce company as not all readers may be familiar with the organization. Consider including: company specialities, location, size, industry.
• Typically you can source much of the content from the company's marketing material.
• Usually you won’t include everything the company does, but rather focus on the area of interest to this case study.
• The Challenge:
• Set scene: 1 to 2 paragraphs: <XXX Company> wished to <achieve some goal/functionality/solve some user need>.
• <Image>:
• Provide relevant hero image(s), covering ~ 1⁄3 of the page(s). Try to convey as much meaning as possible. Typically use a contextual photo, screenshot or flowchart or infographic. Don’t embed working demos here. We want to minimise our doc maintenance and draw the reader into more advanced pages.
• Ideally have at least one image on each page.
• The Solution:
• 2 to 5 paragraphs.
• Explain how this has been implemented. Sparingly link to Learnosity feature pages mentioned.
• Explicitly state the value (time, money, reliability, new business, better student engagement) gained by using Learnosity. Where possible, source compelling stats or figures to support statements of value. These will ideally be provided by the customer if they are prepared to share.
• Use domain-specific lexicon rather than Learnosity lexicon. We aim to use language a reader is already familiar with rather than confusing them with jargon.
• Quote(s):
• Ideally source quotes from the customer. This could be one hero quote at the end, and possibly one or two quotes in the body of the text.
• “<big title> at <XXX Company> said that Learnosity's product made our project simpler/faster/more intuitive/more reliable/....”
• More info:
• Provide links to relevant Learnosity documentation (Typically point to concept descriptions within Guides/Knowledge Bases, Demos, maybe Features, probably not Reference pages.)
• Output format:
• HTML on www site (mandatory)
• PDF (optional - for high value case studies). PDF will require extra effort to layout the content nicely on a paper page.

White Paper

Description: A white paper describes the business consideration (which might reference technical concepts from a business perspective) related to the complete implementation of a Learnosity based solution within a specific domain. Aim to help a potential customer understand all the technical complexity involved in implementing their solution, and by implication, have them appreciate the depth of knowledge we have in this domain. This aims to provide unbiased information, and should try not to be an overt sales pitch. It should have well-constructed business discussions and technical implementation considerations, backed by research where appropriate.
When to write:

• Writing a White Paper will be a lot of work, and the paper likely will have a lifespan just a year or two (as we will be referencing versions of software and current research which will become dated).
• A reason for writing a white paper will likely be triggered by wanting to pull in a specific big client. We tailor the white paper for the customer, but make it generic such that others can use it.

Length: 5 to 10 pages, including diagram(s)
Target Persona(s):

1. Software Systems Architect.
2. C-level decision maker.

User Stories:

• TBD.

Doc Structure:

• Title: The title should describe a concept that we are explaining.
• Executive Summary:
• Concepts:
• Conclusion:
• More info: Provide links to relevant Learnosity documentation

Features

Description:
Features on WWW allow us to define and display specific functionality in a product marketing voice. They should be short outlines that have more showing focus than reading.
Length: Less than 500 words (two to three paragraphs ).
Level of detail: Tell your mum how a given Learnosity feature works and/or its value
Target Persona(s): (in order of importance)

1. Product Manager,
2. C-Level/Decision maker,
3. Developer,
4. Author (of questions/assessments).

Assume prospective client can be from any of our verticals, and this is an entry point. So don’t speak to specific APIs or unique Learnosity terms. Keep language accessible to the first-timer.
User Stories:

• As a generalist Product Owner or C-level executive (CEO, CTO, etc), I want to find out why using Learnosity would provide a better, more engaging experience for my learners and instructors. I’m also interested in the business advantages my organisation could gain by spending money on Learnosity. I’m likely researching a purchasing decision.
• As an author or developer I’m wishing to quickly understand what a feature provides. (I might have come to this feature page from a link somewhere else in Learnosity docs).

Content Do's:

• Do talk about meaningful products/features.
• Every feature should be presented with the value it brings to potential customers and an example where appropriate. What does it enable users to do and why is this useful.
• Reinforce Learnosity's expertise in the area if possible and appropriate.

Content Don'ts:

• Don’t capitalise Learnosity terms, such as “Question”.
• Don't talk about specific APIs or lower-level components.
• Don't use unique "Learnosity-specific lexicon" here with its special meanings and interpretations. As far as possible, use general plain English to describe the subject matter.
• Don't use specific industry jargon or buzzwords. No "web-scale", "MCQ", "KPIs", "Cloze", "RAID", "Modal", etc. Spell out acronyms, so “MCQ” becomes “multiple-choice questions”.

Demos:

• Use live polished demos where appropriate with succinct and relevant context.

Site Map

We have a complicated site, with a lot of content.

• We should create a site map page.
• This task should also cover creating consistent header and footer information between sites.
• We should also be considering the User Journey and restructuring as required.

Conceptual Overviews

Description: A group of overviews which bridge the gap between Marketing and Technical documentation by introducing technical concepts.

Overviews:

1. Conceptual Overview - Learnosity Pillars: A high level overview which introduces the Authoring / Assessment / Analytics pillars.
2. Conceptual Overview - Hierarchy of Learnosity components: A high-level overview which introduces the Barbusca doll of Questions, Features, Items, Assessment, Web Page.
3. API Relationship Overview: Extend API Overview to show what API embeds in the other.
4. Infrastructure Overview. What lives in the cloud, what is in the browser? How do you develop and then manage a Learnosity based site?
5. Learnosity Web Development Overview: Explain functionality from an Developer's perspective, “Hello World” description. Introduce use of HTML, JS libraries, CSS. Leads into Quickstarts.
6. Learnosity Author's Overview: Explain functionality from an Author's perspective.
7. Learnosity Teacher's Overview: Explain functionality from an Teacher's perspective.

Quick Starts

Description:
Provide one very simple example, that it is easy to copy, understand, and get running.

Target Persona(s):

• Product owner or trusted developer who has enough programming experience to read and understand code.
• Might be an ex-programmer with dated programming experience.
• Currently has very little exposure to Learnosity documentation or terminology.

User Stories:

1. As a Product Owner or Trusted Techie, I want to Skim Read the API Quickstart Text so that I can quickly assess the effort required to implement the API and whether it might fit into my system.
2. As a Trusted Techie, I want to implement the API Quickstart so that I can verify that it would be easy to implement the API and modify to my purposes.

Doc Structure:

• Overview:
• What this quickstart is covering.
• Introduction to the technology and concepts.
• Time to complete.
• Prerequisites
• Download
• View example
• Explain each section of the code, step by step.
• How it works
• Next steps / Related links

Provide:

• Screenshots
• Links to code that can be cut and pasted
• Link to an environment which can be downloaded and deployed

Key Message(s) to convey:

• How to get the simplest version of an API running
• This API is easy to set up and run
• High quality (of code and docs)

Content-Length: Run within 10 minutes

Reference Docs

Description:
Provide automatically generated function and parameter descriptions (presented in a similar format to javadocs). Reference material is product-centric. It aims to describe every public method and attribute of a public product.

Target Persona(s):

• Software developers who are implementing Learnosity products, who already have an understanding of Learnosity product terminology.

User Stories:

1. As a Software Developer who is implementing a Learnosity API, I want to understand the specific API options so that I can customise the Learnosity products I am integrating into my product.

Doc Structure:
Include tables of <param> : <description> : <options> for:

• Initialization Options
• Event Options
• Public Methods

Tutorials

Description:
Provide a working description on how to implement a specific feature, sub feature or task.
Target Persona(s):

1. Software developer, with at least a limited understanding of Learnosity products.

User Stories:

1. As a Software Developer, I want to learn how to implement a specific Learnosity feature/sub-feature/task, so that I can easily implement it into my specific software system, and play with different configuration settings.

Doc Structure:

• Title: A concept, such as “Styling” or feature such as “Paper based assessments”
• The Title should help identify “why” a person will want to read this Tutorial.
• Overview
• Describe what this quickstart is covering in ~ two sentences.
• Where appropriate, include one screenshot, or a collage, or diagram to help quickly convey meaning.
• Time to complete
• Example
• Provide a reference to an example of this functionality working. This should be available within www/Features and/or Author Guide.
• It is better to reference an example than to embed it. It helps set a common language for authors to talk to developers, and also reduces maintenance of documentation.
• This example should also be available as a downloaded zip file.
• Background
• Introduction to the technology and concepts.
• How it works
• Provide link to example source code.
• Explain concept and goal for each step.
• Provide screenshots where appropriate.
• Show code snippets and explanation.
• Next steps / Related links

Training Course

Description:
At some point we will have a need for formal training courses. The material should draw heavily from Tutorial material. The training can be used for onboarding new employees initially.

Author Guide

TBD

Developer Guide

Description:
The developer guide consists of a series of documents, with each document explaining a specific “concept”, such as how to implement specific functionality. Documents should aim to build upon each other, starting simple and getting more complex. As required, documents should cross-reference each other.
What makes it a guide:

1. Technically explains “how to” do something (as opposed to sales messages)
2. Deals with core functionality as opposed to edge cases.
3. Deals with concepts which are common to multiple APIs.
4. Deals with multiple concepts rather than a single one.
5. More than just “extended technical information”.

Target persona(s):
The target persona and expected prior knowledge will be different for each guide section. Typical personas will include:

1. Competent software developer who is unfamiliar with Learnosity and needs to learn new Learnosity concepts.
2. Software developer with Learnosity experience, wishing to implement an advanced Learnosity feature.

Doc Structure:
The Doc structure will be similar to Tutorials.

Knowledge Base

Description:
Describe details required to understand and implement an attribute/feature which is too complex to explain within Learnosity's reference documentation and too domain-specific to warrant the effort of writing a tutorial or solution.
Target persona(s):

1. Software Developer who already has already set up a working Learnosity development environment and is familiar with Learnosity documentation.

User stories:

1. As a Software Developer , I want to understand concepts behind a specific Learnosity feature so that I can implement the associated functionality.

Length: 1/2 - 2 pager (200 - 1000 words)
Doc Structure:

• Topic: A concept or feature or attribute within a specific Learnosity API
• Overview
• Describe what this Knowledgebase is covering in 1 to 2 sentences.
• Where appropriate, include 1 screenshot, or a collage, or diagram to help quickly convey meaning.

Guidelines:

• Don’t explain something that should be assumed knowledge.
• Focus on one concept. If you need to explain another feature or method etc., link to it.

Glossary

Description:
A table describing all the acronyms and lexicon used by Learnosity.
Learnosity ministry of Lexicon:
In moving forward, all new Learnosity terms should be put into the Glossary. For a term to be added to the Glossary, it should be considered by the “Ministry of Lexicon” and interested parties should be provided with the opportunity to refine lexicon selected.
Target Personas:

1. Anyone involved in Learnosity.

User stories:

1. As someone using Learnosity, I’d like to understand specific acronyms and terminology used by Learnosity.

Guidelines:
We should be hyperlinking to acronyms and terminology used by Learnosity, which should reduce replicated descriptions, and make content cleaner and easier to read.

Tooltips

Description:
Embedding tooltips enables information to be delivered “just-in-time”, enabling it to be available as it is required. Tooltip text would come from the Glossary.

FAQ Troubleshooting - Error Codes

Description:
Provide a table of error codes, descriptions, and steps to follow when receiving these codes.
Target personas:

1. Partner developer, product developer, end-user (teacher/student)

Release Logs

Description:
Describe all the fixes and additional features added in the latest release.
Target Persona(s):

1. Product owners and Techies with deep understanding about how their products are using Learnosity functionality.

User Stories:

1. As a Product Owner making use of Learnosity Tools, I want to know what features have been updated/fixed, so that I can assess whether there is a business driver for me to update to the latest release of Learnosity.

Community Forums

Description:
Provide community forums, with the aim of having bi-directional conversations. Typically:

• Developer asks question.
• Learnosity polls community about future development direction.
• Community/Learnosity provides multiple answers.
• Community votes up best answers.
• Where possible, answers point to existing docs. Popular topics should be “matured” to Knowledge Base articles or Guides.

Vision for community forum:
We care about our customers and they care about us. Mutual respect and reciprocity is part of what has made us successful. It is about sharing what is easy for you, and receiving what is easy for someone else. Our aim for the community is to scale our relationship of mutual caring and support those in our communities who are wanting to help each other.

Community Win Formula:

1. Demonstrate commitment
2. Everyone gets more than they put in
3. Need help
4. Expect help
5. Appreciate help
6. Simplify contributions
7. Engage
8. Care about each other

Value Goals:

• Have our users feel a sense of ownership and loyalty for our Learnosity product:
• By contributing to the direction of Learnosity.
• By feeling part of a team.
• By helping vote up priority features.
• Ensure everyone in our community gets more out than they put in.
• Help our user communities connect with and help each other.
• Reduce support costs by:
• Having users search for answers before asking questions.
• Have user community answers other user questions.
• Provide a low-cost sale which only has community support (no paid support)
• Provide a location for our userbase to raise ideas, vote up the importance of ideas, which in turn can be used to collectively lobby Learnosity for feature development.
• Provide a space to collate random ideas about Learnosity functionality without requiring professional quality control and review.
• Provide a means for users to search for related problems.
• Gain insight into our user's pain points from user usage patterns.

Implementation Goals:

1. Keep it simple.
2. Grow organically, starting with just one or two forums.
3. Best practice suggests attract 5-10 posts/day to achieve a healthy community. Don’t split until you get 30 posts/day.
4. Minimise extra work for Learnosity, by continuing to do what we are already doing - but moved to be within a community forum. In particular by moving many answers from the support team into community pages.
5. Soft launch with “Beta” stamp.
6. Only attempt to engage current customers/partners/authors (initially).
7. We need to provide the opportunity for our community to engage and feel needed:
1. If we answer every question straight away, we don’t create a space for others in the community to build a reputation and find a space to engage.
2. Community engagement needs to result in positive action from Learnosity. It needs to be valued and valuable. We need to trust our community and implement their recommendations, otherwise don’t ask. Respect their time.