How to document your projects and don't die trying

How to document your projects and don't die trying

Learn why and how to make your projects clear for others...

Featured on Hashnode

📕 Some background

Before I started all this journey in learning web development, I was passionate to write and teaching people about the things I've learned (and still, this blog is the proof).

I work on a big company that has created several applications, and customers use them as a service (SaaS) and I work providing technical support to customers, filling out bugs, reporting issues, or guiding customers to configure their service as their use case.

In that type of job, you can find smart team members who, that as side projects, they create small applications, services, or browser extensions to make our work easier. Some of my team members have created smart scripts to automatically send emails, a case comment generator, or a tool with KPIs and metrics but to deploy those tools to our colleagues in the company, they needed to create a user guide, and they struggle with it.

Discussing that with a Sr. engineer, he told me that developers don't like to document, it's tedious and that was an interesting fact I knew about developers. Do you feel identified with that?

🤷 Why is it important?

I didn't understand why my colleagues wanted help documenting their tools. I imagine that they think it's a waste of time because tools are intuitive enough to work with and it's not necessary.

Or maybe it's because they can focus more on coding rather than explaining simple steps to users. However, we don't know how other people will react to your app or if there's an area of opportunity you need to fill out.

✅ Clarify the right use of your app

Some users will try to identify a use case for your app and what's the best context to use for. You, as the creator of the app, are the one that knows the answer, you know what's the need that your app will fill out.

Explaining a good motivation in the documentation is always good to align users with your goal, so they'll get the most out of your app.

✅ Show all the features

Depending on your app features, some of them will not be needed for your users. For example, if the main feature of the app is to create automated tasks and schedule them in a calendar, your users will know that it's the only way to use the app. But what about if you also have features like sending an email after creating the task, sharing the task to colleagues, adding profile information, getting a completion report, etc.

Documenting is the opportunity to show how the app can be used and all the features that can be used with it.

✅ Gives you exposure

If you want to sell the app or gain more users, you can use the documentation as a selling point, documentation is the way your prospects or potential users will know what's the app for.

If the app requires membership or an authorized login, you can add the documentation to your portfolio, so users will check if that's the app they need.

You may argue that you only need a good landing page to show up everything, but believe me, some people (like me) like to read all the documentation, pricing, detailed features to confirm if that's a good app to sign up for or not.

✅ Your app will be taken seriously (what about if you scale?)

Most famous apps have documentation because they want users to be fully aware of features and the right use of the app.

Imagine you buy a brand new TV and it doesn't have a manual guide. Everything seems intuitive, then you encounter that if you want to configure additional apps, you need to add a default password provided by the manufacturer and you don't have it.

Those details get users angry and they have to spend time with tech support to solve that issue, something that can be solved by having clear documentation.

It's also important that if you scale, and if you have good documentation, tracking all your features and steps to configure the service will be easier at the end.

✅ Maybe the app is not too intuitive as you think

You, as the app developer, know all the features and how to go to every step, and I think if that's an app that you only going to use yourself, you don't need documentation, however, if it's an app you will share to other people, they can provide you feedback.

We work as our mind is built, and it's not the same way as other people's mind is built. So you can explain the features as you think they need to be used.

🤔 How?

Documentation is important, fill out your motivations there, now how can we do it?

🧙 Know your audience to choose the right words

It's not the same to build an app for developers, executives, or end-users. It will depend on the people who will be using the app. If you use complex terms for users that don't know anything about web development or app deployment will be counterproductive.

The same as if you build an app for developers, creating documentation explaining what are HTML tags, will be overwhelming as the documentation will have a lot of unnecessary information that every developer should know.

Empathy is put yourself in other's shoes, so, you will need to answer the question: How can I use this app with the knowledge I have? or What's the best way I'd like to have this information presented?

After you understand what's the knowledge of your target audience, you need to start writing the instructions and describing features in the same jargon as they want to be interested in reading.

⌨️ Organize the project features

It's important and useful that while you're creating the app, you're documenting. As per my conversation with my friend, I know that's not the case most of the time and then you need to document everything after the app is done and you don't know where to start.

This is a basic outline I follow when I'm documenting, you can follow it as you need it:

1. App description or overview: Describes what's the app for and the best use cases.

2. Objective or motivation: Tells your users your motivation to create the app and the issue you are trying to solve.

3. Release notes or version updates: As the app scales, you can keep a control versioning system, it also applies to your documentation as you're adding new features or solving bugs.

4. Features or user stories: This is the core part of your documentation. As a suggestion, describe every user story. If there are user stories that show in other pages within your app, describe them first and then describe the unique ones.

The first feature you will describe is the first feature the user sees as they open the app and so on. Describe every detail from top to bottom and from left to right.

5. Troubleshooting and support: Some people will encounter issues while using the app, maybe it's part of a known issue and you know how to solve it, you can add some troubleshooting steps or just add a way to contact you (the most common one is to fill out a form with an issue description.

6. Feedback: If you want to improve, please this section is very important, ask for feedback or feature ideas/

🕶️ Images are good but not too much

I use images in my documentation, however, having a lot of images can be overwhelming.

You can use just a screenshot for big sections, or user stories. Features that show on every page or part of your app can also be useful to include in the documentation as images.

Remember that if you are documenting, the user will go directly to the app and they don't need to watch the same image in the documentation. Focus on the images that you think the user will have difficulties finding out where they're located.

🔧 Tools to document

Here are some ideas you can get on the tools you need to document better.

Google Technical Writing courses

I strongly recommend you continue training on your documenting skills. In those courses, there are some details you'd like to take into consideration such as grammar or audience.

It also gives you an idea of how to organize the topics in the documentation.

Google Docs or MS Word

If you are with the KISS mentality (Keep It Simple Stupid). You can document using Google Docs or MS Word and share the document with your team or end-users.

In the end, remember that you need to provide a clear description of your app, and the tool you use, might not matter for that.

Notion or Evernote

If you want to take the next step in in-app documentation, you can use these tools like Notion or Evernote, they're specialized in note-taking and it's easy to organize topics and features.

You can also tag or classify the topics and they have a nice style to present to end-users.

Documentation packaged app

If you want to continue being simple, you can create a README file using markdown, that's a good alternative if you use a web app. Or my recommendation is to use a documentation packaged app.

I shared an article for you to choose the best documentation app, my favorite ones are Docusaurus or GitBook.

Look for a specialist

If it's not mandatory at work and if you don't want to document because it's boring. Look for a specialist, someone that likes to do it and do it great. I added my email me@davidsalomon.dev if you want to contact me and I can double-check your project and provide you ideas on documentation or if you want me to help me documenting your project.

However, if you don't want to go that way, you can go to platforms like Fiverr and hire the services of a technical writer.