Alyss has been working in tech since 2012, with diverse experience in Sales Engineering, Developer Advocacy, and Product Marketing with companies such as GitHub, Box, Atlassian, and BigCommerce.
Before you do anything else, version control is just as important for documentation as it is for the underlying code. As a project continues to evolve, so will the docs. This can be hard, depending on what platform you are using to host the documentation. For a past project, I used slate which allowed me to utilize Git. Check if you can use Git, markdown files (or another markup file to store in Git), and if your docs platform supports backups.
Think about user personas
Once you've been working on a project long enough, it is easy to lose sight of what a newbie would need to know. Spend some time to write down who you think will use the docs, what knowledge you think they will already have, and what knowledge they won't have. Use that context to guide your information architecture.
As an example, if I were documenting how to create a webpage hosted on GitHub pages, I would split things up into something like:
Getting Started (markdown formatting, how to deploy)
Next Steps (Selecting a theme)
Advanced (Creating a theme, custom domain names).
### Lead with uses cases
One of the first things I'm trying to understand when I find a new npm package, phone app, or open source repo is to understand why I would want to use it. In fact, when I find a repo that I need to use which doesn't have a good readme with use cases explained, I make one and open a pull request.
Depending on what you are documenting, there's two core ways to cover this. The first is with sample code. Twilio has a great example of this on their SMS landing page which reads "Send your first message" as a call to action. The second method is to write exactly what you intended the project to be used for, what you didn't intend it for, and what others have done with it so far.
Take feedback
Make sure you have a mechanism for finding out how good your documentation is. Try to avoid anything that requires a login (e.g. GitHub issues). If you can't, that's okay but keep in mind that it creates a barrier to getting actionable insights. You can capture feedback using a feedback form, a public trello board, a community forum, a subreddit, et al.
Add website analytics
Another good addition is Google Analytics. It will allow you to see how long someone stays on a page, what page they enter the site from, and where your users are coming from.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Use version control!
Before you do anything else, version control is just as important for documentation as it is for the underlying code. As a project continues to evolve, so will the docs. This can be hard, depending on what platform you are using to host the documentation. For a past project, I used slate which allowed me to utilize Git. Check if you can use Git, markdown files (or another markup file to store in Git), and if your docs platform supports backups.
Think about user personas
Once you've been working on a project long enough, it is easy to lose sight of what a newbie would need to know. Spend some time to write down who you think will use the docs, what knowledge you think they will already have, and what knowledge they won't have. Use that context to guide your information architecture.
As an example, if I were documenting how to create a webpage hosted on GitHub pages, I would split things up into something like:
Depending on what you are documenting, there's two core ways to cover this. The first is with sample code. Twilio has a great example of this on their SMS landing page which reads "Send your first message" as a call to action. The second method is to write exactly what you intended the project to be used for, what you didn't intend it for, and what others have done with it so far.
Take feedback
Make sure you have a mechanism for finding out how good your documentation is. Try to avoid anything that requires a login (e.g. GitHub issues). If you can't, that's okay but keep in mind that it creates a barrier to getting actionable insights. You can capture feedback using a feedback form, a public trello board, a community forum, a subreddit, et al.
Add website analytics
Another good addition is Google Analytics. It will allow you to see how long someone stays on a page, what page they enter the site from, and where your users are coming from.