Software Documentation: The Nickelled Guide

"Software documentation is a good thing."

"Too much is better than not enough."

Both of these things are true, but there aren't unlimited hours in the day, and doing a good job of preparing software documentation often gets overlooked.

Here's the truth though: having good documentation can make or break a software launch or deployment.

It can make the difference between a product that users love and a product to which users will never return. And it can make the difference between a profitable year and increased overheads in the form of extra support costs.

Put simply, software documentation is worth getting right – and in this guide, we'll show you how.

But first, baby steps: What is documentation?

######Chapter 1

What *is* software documentation?

Software documentation can do any of the following:

• Specify the intended uses of the software: this can be anything from a concise sentence to a long document, describing the intention of the software rather than the implementation.
• Explain how the software works: this describes the implementation of the software.
• Instruct the user on how to use the software: detailed documentation to explain how to perform all manual processes in the software.

Ideally, the documentation for the software would serve all three purposes. However, documentation is generally more user-friendly when it is written for a single purpose.

So, ideally specification, explanation, and instructions are all written and labeled separately, rather than buried amid a single piece of documentation.

Who is the documentation for?

Like the software itself, there are different types of user who will want to use the documentation – and a bunch of side use cases who will also find it useful. Here are some typical users who might need documentation:

• Viewer: someone who looks at work produced in the software, but doesn't make any changes. They may need the documentation to better understand what they are looking at.
• Player: someone who interacts with certain information contained in the work done in the software, but doesn't create the work itself.
• Changer: someone who makes changes to things like layouts and formulae to correct and enhance the work done in the software.
• Developer: someone who makes major changes to the work the software does, including writing code and implementing the work from scratch.

The same individual might use the software in more than one way during its lifetime. Users are characterized by the role they play at any given time, rather than any roles they are capable of playing.

There are also other stakeholders who have an interest in documentation - support teams being the most obvious, but also marketing, sales or customer success.

The two basic forms of documentation

There are two clear ways documentation can be included with software:

a) It may come in the form of a separate document, usually for long and formal specifications that need to be reviewed and signed off themselves.

b) It may be implicit documentation: incorporating information and help into the software so that it becomes available whenever the user encounters a certain scenario.

The latter is particularly suited to instructions and explanations and is commonly written into the code so that it appears as a seamless component of the software itself.

As you read on past this chapter, remember this one essential fact:

Just about everyone benefits from quality, accurate documentation.

Ultimately, the software provider should see the benefit to its own bottom line of providing documentation. The primary benefit is the role it plays in reducing the number of calls and messages from users who need help using the software. By providing comprehensive documentation, you will offer a built-in, passive support system that answers the vast majority of questions the users may have.

This way, you don't have to allocate as many resources to providing user support, reducing your expenses and enabling you to focus on more important business tasks.

######Chapter 2

Building a Curriculum

Every software documentation project starts with research.

It might sound like an obvious point, but you need to know what to document, the purpose of documenting it and how detailed your documentation will need to be.

To get this right, you will need to liaise with people in your organization who deal with help tickets and support calls to understand where the majority of issues are coming from. You will also need to identify key processes that users need to understand to be able to achieve anything with your software.

It's best to build a documentation plan or a curriculum. This will be an outline that helps you navigate through the project, and it should include the following:

• Goals: What do you want to help users to achieve? Is it simply to use your product? Or to find the help section quickly? Learn some of the more intricate aspects of your software? Establishing a precise and clear goal of your documentation will help give you direction and produce quality work.
• Other resources: What's already out there to help users? Are you updating existing resources or merging them together? Do an audit of all existing content to find everything that will help you write, and to remove anything that might confuse your audience.
• Style requirements: In some industries, technical documentation must be written in a specific way. Furthermore, some companies have style guides for the tone of voice that users should expect from the brand. Make sure you adhere to the necessary style requirements in your documentation.

The overriding goal of any software documentation is to be usable. A huge part of this is ensuring it is structurally logical, easy to navigate and well written. Before you even get to grips with creating content, you need to consider how that content is to be presented.

This means also thinking about on-page design, as well as the navigational structure of your documentation. What order will it be presented in? How does the user move around the content? Which documents will be connected or linked? These are the questions you need to be answering.

Introducing the ultimate documentation hack

If you create superbly crafted software with no documentation, your users will struggle to understand how to use it and opt for a more user-friendly alternative.

People need help figuring out how to use new tools, and solving this problem isn't rocket science:

Write your 'Readme' first

This means before you write any codes, tests or behaviors at all. This might not feel natural to a programmer, but writing a good Readme to drive your creativity is essential to ensure you have quality, coherent software to show at the end of it. Until you've written about your software, there's no way of knowing what you're coding.

This doesn't mean going as far as waterfall design, specifying huge systems in minute detail before even getting started. But if there is no documentation present, then you go too far in the other direction, losing perspective and structure.

There has to be a middle ground between producing meticulous technical specifications and producing no specifications at all.

That middle ground is the Readme!

Readme Driven Development (RDD) is something like a limited version of Documentation Driven Development (DDD).

By keeping your design documentation in the form of a single file that introduces the software, you protect yourself against the risk of DDD-turned-waterfall by restricting you from producing overly detailed content.

This helps subtly push your software development in the right direction without being too meticulous in specifying what you can and can't do.

Writing the Readme first has some substantial advantages:

• It gives you an opportunity to think the project through without being too restrictive in your creative options. When we write automated code tests we capture all kinds of errors that otherwise would have crept into a project, and writing a Readme upfront gives us a similar feeling.
• Your Readme will help you know what needs to be implemented and stand as a handy piece of documentation to present to the user. And you'll feel far more passionate and motivated about creating this content ahead of time - writing it retroactively can be tiresome and laborious, and you'll be more likely to miss important details and write with less vigor.
• If you're part of a team, a Readme can help everyone get on the same page from a software architecture perspective. Anyone doing further software development projects that will interface with your code will have a good understanding of how that will work, and this can prevent problems down the line of having to re-implement significant pieces of code.
• It's easier to have discussions about something that is written down because it gives everyone a clear idea about what needs to be debated and focused on.

Consider writing your project's Readme as the truly creative aspect of the project.

All your ideas can be expressed with clarity at this stage, and the document should be able to stand alone as a testament to your creativity and vision.

######Chapter 3

Choosing a Format

What type of documentation are you creating?

The documentation that comes with software generally performs one of four functions:

1. A tutorial,
2. A 'how-to guide'
3. An explanation
4. A technical reference document

Each of these functions requires its own, distinct style of writing. Anyone that uses your software will require these different types of documentation in different circumstances, so you'll probably find that most software will need all four. When you produce your documentation, you need to structure it specifically around the intended function, and you need to keep the four types of documentation separate from one another.

The tutorial

• This is a learning-oriented document.
• It should enable the newcomer/beginner to get started with your software.
• It is a lesson and should read as such.

You could compare this type of documentation to teaching a young child how to use the tools and equipment required to cook a meal.

The how-to guide

• This type of documentation is goal-oriented.
• It should demonstrate how to solve a specific problem.
• It should be presented as a clear series of steps that can be easily followed to achieve a goal, potentially using tutorial software such as Nickelled

A good comparison for this type of documentation would be a recipe in a cookery book instructing the user on how to prepare a specific meal.

The explanation document

• This is a type of documentation that is focused on increasing the user's understanding of the software.
• As you would expect, it should explain things in much more detail than a tutorial or a how-to guide.
• It provides context and background to functions and processes to help the user achieve a more profound understanding of the work they can do with your software.

You might compare this type of documentation with an article on the social history of culinary culture.

The technical reference document

• This is an information-heavy document that users can easily refer to for key information, including source code where required.
• It should describe the machinery and processes in a straightforward but comprehensive manner, down to how it feels into the overall software architecture.
• It must be accurate and complete to be fit for purpose.

As a point of comparison, you could think of this type of documentation as being similar to an encyclopedia article.

This division of four types of software documentation makes it clear to both the author and the reader where different types of information belong.

For the reader, it allows them to find an answer to their question in the most efficient way, getting simple answers to simple questions and detailed answers to detailed questions.

From our perspective, it gives the author an idea of how to write, what to write, and where to write it.

This will save a significant amount of time that would otherwise be spent on trying to organize the information you want to impart into a logical and coherent structure. Each of these kinds of documentation has a specific job, and you can divide your writing between them.

It's very difficult to create quality documentation if it doesn't recognize these quadrants, whether implicitly or explicitly.

Each kind of documentation has its own distinct demands and language, so if you attempt to ignore this structure you will find yourself being pulled in multiple directions at once. Develop a good understanding of the structure, and decide which of the four types of documentation you're aiming for (or how to divide the information into the different types).

######Chapter 4

Software Documentation Services

There are various types of software documentation tool out there to help you produce your content. Let's take a look at your options:

Knowledge Bases

A knowledge base is an online library of information regarding a service, product, topic or department. The data contained in a knowledge base can come from anywhere but is usually sourced from contributors with strong working knowledge on the subject who can provide all the pertinent details. In the context of software documentation, the subjects will revolve around how the tools within your software work. This can include things like troubleshooting guides, FAQs and other useful content that fits one of the four main documentation types listed in the previous section.

A knowledge base combines with a program of knowledge management to continuously create, curate, share and utilize expertise on your software. When you have a strong knowledge base in place and a knowledge management program, you have extensive documentation that is agile and ready to deliver a swift support service. And with the easy addition of regular updates, your documentation will always be as current and all-encompassing as possible. You can even include a forum where users can ask questions and support one another in solving problems, further reducing the burden on your own support staff.

The advantages of a good knowledge base include:

• Every piece of documentation users need to know is put in a single, well-organized place.
• It makes your company look innovative and professional.
• It provides standardized answers as opposed to multiple responses to the same question.
• It provides a feedback loop and an opportunity to interact with the people that matter.
• It's an agile solution, meaning you can customize it to work the way you want it to.

E-learning platforms

An e-learning platform is a set of interactive online services that provide information, tools, and resources to train and educate users in the functions your software has. There are many services out there that can help you create your own e-learning content, handling the nuances and complexities of their platforms so you can focus on your enterprise and the information you need to impart. The e-learning partner you work with will support you throughout the creation of your documentation, and you can expect the following benefits from a quality provider:

• The focus will be on content that improves the end user's skills with your software.
• Complex courses will be broken down into comprehensible chunks to facilitate a step-by-step learning process.
• Learners will be able to discover their own objectives and engage with the training content.
• There will be the option to add to and expand the content.
• The presentation of the content will be optimized to increase effectiveness and comprehension.

You should shop around for different providers of e-learning platforms to find one that meets your basic criteria and budget requirements. Look for providers who work with businesses of all sizes, and take advantage of any free trials to see if their software is likely to work for you.

Learning Management Systems (LMS)

This is another platform for delivering educational courses and training programs for users of your software. It enables you to comprehensively manage the courses, meaning you can create them, make changes to them, assign them to learners and grade them. It is software that supports the creation, management, and delivery of e-learning courses, and it generally consists of two component parts:

1. The server component that performs all core functions.
2. The user interface that runs inside a browser whereby admins and learners can access the content.

An LMS is an invaluable tool for helping people learn every element of the functionality of your software. This can be useful for independent users, company employees, and anyone else using your software who needs to improve their knowledge and skills to get the most out of the tools provided. With cloud hosting and the ever-growing digital world, e-learning is becoming an increasingly common presence in the creation of software documentation, and a Learning Management System is a superb way of providing this for users of your software.

Should I build, pay or adapt?

When you are mulling over the options for how you can provide your knowledge base, e-learning platform or learning management system as documentation for your software, you have three basic options: you can self-build, you can use a paid solution, or you can adapt an open-source option. There are advantages and disadvantages of each, so let's break it down a little.

Self-build/self-hosted documentation software

This could be a system that you download from a vendor and host independently or one that you build yourself from scratch. In some cases, you may even get the software to self-host in the form of a physical software disk. When you self-build, you get complete freedom to create the documentation in the way you see fit, presenting it to users in an entirely customized way. Of course, doing this effectively will require you to have the skills to create the platform - it will be like writing an entire piece of software to support your other piece of software. Here are some pros and cons to think about:

Pros:

• You get the freedom to create the knowledge base or e-learning platform entirely to your own specifications and take complete control over the hosting and running of it.
• You don't have to pay any money to a third party to create/host content.
• You don't have to liaise with other people to create the content (unless you need to hire a copywriter to create the written content).

Cons:

• It's a lot of extra work to program an entirely separate system to support your main one.
• Hosting invariably costs money.
• You won't have the expertise of people who specialize in creating and managing knowledge bases and e-learning systems to help you.

The paid option

When you opt for a paid solution, the most common tools are cloud-based in a Subscription as a Service (SaaS) model. The platform vendor will handle the maintenance of the system and carry out any tech updates or upgrades. They will provide the system for users to log into, hosting it and managing user interactions on your behalf. You won't need to create or install any software, making it a great option for anyone who wants to get started quickly and with minimal hassle. You will find that there are limitations to the amount of customization you can bring to the table, but this is the compromise you make to have a fully-featured knowledge base or LMS created and hosted for your software without having to do all the groundwork yourself.

Pros:

• It's quick to get started.
• You will have a partner to handle all the legwork so that you can focus entirely on the content to be included and, most importantly, on creating your actual software. What's more, that partner will have all the experience and expertise you could hope for!
• You don't have to worry about the tech side of things - upgrades, updates, and hosting are all managed for you.

Cons:

• You will have to pay a monthly fee to cover the service, and this will eat away at your bottom end.
• You are limited in terms of customization options. For example, you may have fewer opportunities to incorporate your own branding, and may not be able to personalize the dashboard.

The open source option

When you choose an open source system, you will get a piece of software that is free to use and can usually be downloaded online. You will then be free to adapt it to make it better suited to your needs. Additionally, many open source tools have very active online communities, which means that you will have access to troubleshooting and tips assistance free of charge if you encounter a problem. Any programming experience will be a bonus here, because you can modify the software to your heart's content, making your knowledge base or e-learning platform look and function just how you want it to. This is a great middle ground between the other two options, because you don't have to start from scratch, but you are able to make all the changes to the back-end that you want to.

Pros

• You get a pre-made platform that's ready to go, free of charge, and you are permitted to customize it to your heart's content.
• You can make changes to the platform as you go along.
• You have access to an entire community of other people using the open source software for tips, advice, and troubleshooting.

Cons:

• You still have to manage everything yourself, taking time away from working on your primary focus: the software you are creating documentation for.
• You will have to pay for hosting, unless you have the resources to self-host, to make your knowledge base or LMS available to customers.

######Chapter 5

Software Documentation Tools

So, what tools are available?

If you want to provide a knowledge base for your customers, you will need to shop around to find the best tools available for your project. There are various popular paid options out there, as well as some open source options that many software developers choose to go with. Here's a brief round-up of some options that come highly recommended.

Zendesk

Zendesk is a customer service and engagement platform that is flexible and powerful and can be scaled to meet the needs of any business or software.

The platform promises to bring some calm to a customer service world that is often chaotic, and you can expect them to be a partner that will ensure you offer the best possible experience for anyone who uses your software. They offer a selection of products that come at different pricing levels, meaning you can find an option to suit your needs and your budget.

You get to choose the amount of engagement there is with customers, and you need only provide the information that is to be presented and you can let Zendesk compile it in a way that users will find easy to navigate and engage with.

Kayako

Kayako is a help desk software provider that offers a comprehensive suite of tools including live chat that is very easy to integrate.

The award-winning solutions are user-friendly and very affordable for the majority of budgets, and the help desk software is known for providing a high level of customer service in a range of industries across multiple languages.

It is primarily designed to enable a customer service team to engage with customers and software users, but it also provides the ability to deliver dedicated FAQs and other knowledge base tools that enable your software users to discover the support they need without any need to interact with you directly.

HelpScout

HelpScout is another customer service tool that can be applied as a knowledge base platform to deliver the software documentation you need in the way you want it presented.

It has numerous features for collaboration between team members, so if you are more than a one-person operation you'll enjoy the benefits of these tools. It also enables you to deliver a truly personal touch with powerful automation that will help ensure a positive experience for any users who need to engage with your knowledge base.

Freshdesk

Freshdesk is another award-winning solution that is equipped with a wealth of features for delivering quality customer support. It is a scalable tool that can meet the needs of small and large companies alike.

You will be able to broaden your reach through multi-channel support, increase productivity with gamification, streamline operations with automation tools and reinforce customer support efforts through self-service portals. It also focuses on minimizing customer frustration with instant notifications and ticket updates, and is a great way to present your knowledge base to customers who demand fast support and an intuitive way to navigate the information.

Intercom

Intercom is a customer communication platform that is laden with integrated products for all teams. The products are designed to enable targeted communication with customers through a range of digital mediums.

This includes helpdesk products and marketing automation features and can help different members of your team collaborate to deliver the best possible experience for your customers. Intercom is used by companies of all sizes and offers products to suit your needs and your budget.

Essentially, all these knowledge base tools offer a similar service you can take advantage of, so zeroing in on the right one will come down to examining the nitty-gritty. They each focus on specializing in certain key elements to target their own sector of the market, so you will need to get a good understanding of each one to make the right decision for your software.

Take the time to look at their websites and services, and read reviews online to get a good idea of what they could do for your knowledge base. It's an important decision to get the right tools, so don't make this choice lightly.

The most popular open source options:

osTicket

This is an open source IT support ticket system that centralizes all support requests from calls, emails and web form submissions into a user-friendly interface. You can program in auto-responses to inquiries and emails, create internal notes and alerts, and keep track of all tickets that are submitted.

This can be a great way of getting an idea of what documentation is needed once you have launched your software. And with the software being open source, you can edit the code and customize everything to be exactly the way you want it, to deliver all the knowledge and information your documentation requires to ensure your customers are never left without access to the support they need.

You get to choose how much you interact directly with customers, and with the right hosting package in place, you can deal with the number of customers that need to access your documentation with ease.

Helpy.io

Helpy is an integrated support solution that combines and leverages synergies between knowledge bases, support ticketing, and a public community. You can choose which features are activated and deactivated, and you can create a knowledge base that is fully text searchable and SEO optimized to help users find the information they need without contacting you.

It is mobile-friendly and loaded with additional features that you can choose to utilize (or ignore), and the software is fully GDPR compliant. Of course, you still get the same ability to edit the code and customize things to your heart's content, so the flexibility is another great draw if you like to have things work just the way you want.

What LMS tools are available?

An LMS can be a significant expense if you choose to go with one of the popular paid options – in our experience, LMS pricing is significantly more than knowledge bases.

If you want a robust and versatile LMS that can accommodate all the e-learning content you need, there are many open source LMS options that can provide the flexibility you need without breaking your budget. Here's a roundup of the top solutions to consider:

• Moodle One of the most popular options, Moodle features dashboards, multimedia support, and learner tracking. Create mobile-friendly online courses with the ability to integrate third-party add-ons, and take full advantage of the strong user community to help you get the most out of the software.
• Eliademy This has the option of a premium version for a small fee. Enjoy e-learning course catalogs, assessment tools, and mobile apps to help develop learning modules.
• Forma LMS Forma LMS option is packed with features ranging from detailed analytics to skill gap analysis. There are also many virtual classroom management tools, and it is ideally suited to corporate training programs with an active online community as a source of tips and advice.

Some other great options to check out include:

• Dokeos
• ILIAS
• Opigno
• OpenOLAT

Open source Learning Management Systems can offer a flexible and affordable way to create and deploy e-learning courses. And if you take the time to master all their features, the documentation you provide for your software users can be extremely effective. There can be a learning curve with the open source options, but the cost-savings and freedom of design could be well worth the trouble in the end. Make use of online tutorials and active communities if you choose an open source option - they can be a gold mine of information and a lifesaver if you are struggling to get to grips with the platform.

Software documentation tools for internal/developer use

As we have established, software can be an unscalable mountain without good documentation.

This holds true for internal and developer use too, and there are some great services out there to help produce this type of technical documentation.

Software documentation is frequently written in markdown to facilitate hyperlinks and formatting while keeping it plain text, allowing it to exist alongside source code files in version control. Here are some popular services that help to work in this way.

ReadTheDocs

This service is free, which is remarkable when you see that it can do for you. It enables you to create as much open source material as you like, which will be openly indexed on the site.

However, if you want to make the documentation private and internal to your company, this will come at a price. For software documentation purposes, you will probably be fine with having the documents readily available for users, so you shouldn't need to worry about the fee.

The best thing about ReadTheDocs is that you can easily import documentation from other version control systems like Github, Subversion, Mercurial and Bazaar, and it supports webhooks to build documents automatically whenever you commit code.

Github

If you're using GitHub to manage your software source code version control, you have a minimum of a README.MD file in the works. Millions have used GitHub for documenting their software, and it can be as simple as filling that README with your markdown.

If you require more than a single sheet of formatted text, you can leverage GitHub's Pages tool, which provides you with great-looking default themes to make your documentation look slick and professional.

Tettra

Tettra is a knowledge base software that enables you to document your development. It has a variety of potential uses, like having a centralized place where all processes are documented to ensure everyone can see how one relates to another. It can also show how all the various automation that have been built are set up.

Tettra is great for creating an exhaustive library, which means it works for software documentation or something like an internal wiki for your company. It is designed with knowledge management in mind, so it is laden with other supporting features.

There is lots of additional information online to help you learn in depth about what you can do with Tettra, so do your own research and see if it would be a good option for you.

######Chapter 6

How Nickelled Can Help

Wondering what stake we've got in the world of software documentation?

Nickelled makes simple, codeless tools that help you to ensure everyone knows how to use your software. We're unique in the market because we're totally code-free, and our products are used by everybody from small businesses to multinationals such as Pitney Bowes and McGraw-Hill.

Our Nickelled Guided Tours are the easiest, fastest way to document your processes for your employees or customers, with zero integration needed.

Our Nickelled Academies are designed to help you bring new users up to speed quickly, offering highly-personalized courses via tutorials, videos and text articles.

An extra word of advice

You shouldn't feel like you have to stop at documentation. Blog posts are a great way of making your software and the features it has known to a wider audience of potential users. Your blog can offer clarifications about what your product can do, deliver user-friendly and discoverable tutorials, tips and advice, step-by-step walkthroughs and explanations of updates. You can have a blog on a standalone website that is dedicated to your software - perhaps with a forum - around which a strong community might form and expand.

Writing good documentation has plenty of challenges to wrestle with, but it will always pay off a hundred times when you think about how much easier your users will find it to implement your software's many capabilities. This will help increase the popularity of your software, making it more attractive and opening the possibility of other developers investing their time in learning it and making their own contributions to its growth and long-term viability. There are many options for you to consider in the type of documentation you create and the way you create it, so devote time to it and make sure you provide quality documentation with your software.