Why do we need docs?
You may be thinking – I’ve got a million things to do before I can deliver an app to my client, I don’t have time to write documentation!
But consider a time you’ve downloaded a tool, or tried to connect with a component library, or even tried to put together a piece of furniture and discovered that the documentation is impossible to understand or, worse, not there at all.
Consider another time where the documentation was easy to use, and you probably don't even remember reading it – you just followed the directions and it worked.
Which situation would you like your user to face?
This also applies to a time when you’ve tried to work on a group project, or taken over a project after someone else. Isn’t it nice when someone explains what they’ve done, how, and why?
Docs for your team
This is documenting how you made the app in the developer platform. Write them for anyone who may be working on your app, now or in the future.
Even if you're a team of one, it's a good idea to document what you're doing. You may find it obvious what this block of code does now, but don’t expect that you’ll remember all the details in 6 months. It might also be crucial when you will handover your model to somebody else.
An easy way to do this is to use comments in your code. Use it for explanations of “what this does” or “why you can’t delete or move this”, and anything else that you would want to know if you were looking at this code for the first time.
Docs for end users
These are for your app users. They’ll need to know the purpose and prerequisites, setup details, and how to interpret the objects and navigation elements in your layout. If it's a complex app, explain where to find commonly used features.
You may think that if an app is well-designed, it doesn’t need any explanation. That may be true, but it’s not a safe assumption.
Explain procedures for essential functions of the app, even if they seem obvious to you.
Different people interpret an interface, and a procedure, in different ways. Good docs ensure that your user can get their work done, even if they don't “get” your app's logic.
Types of documents
Next, let's discuss different types of docs. For most projects, you’ll need to cover all of these.
Getting started
Overview and general guidance to start using the app: Launch, setup, prerequisites, pages, layout, etc.
Component documentation
This answers “What is…?”
Describe the purpose of the different parts of your app. What does this button do? What is this page for? and so on.
We recommend doing this page by page for the app, so you can describe what the user sees on each screen.
Procedures
This answers “How do I…?”
Explain the process of how to do a specific thing – like upload a new dataset, export results, and so on.
Don’t forget to mention prerequisites for the process. Numbered lists and screenshots are handy.
Template
Have a look at a template (attached) we used for our SC Navigator documentation. It might help you get started when you’re really not in the mood for writing ;).
Feel free to share your own tips in the comments below!