Rust documentation
Background
This is an older project, but I think it still has some useful information. I'll add notes like this to indicate what I would do differently today.
Rust is a systems programming language with a focus on memory safety. I write the language in day-to-day projects and contributions like the VST crate used for creating digital instruments.
As an aside, audio in the Rust ecosystem is thriving. I created the Rust Audio website for the sake of tracking that sort of stuff.
Rust uses a documentation generator to help users understand an API or application (here is one example). However, sometimes maintainers wish to create more attractive landing pages filled with tutorials and example code. Notable examples of these websites include serde.rs, rocket.rs, and hyper.rs. I call these "external documentation sites", as opposed to the docs that Rust generates.
Problem & Solution
The problem with these sites is that they all highlight different information. For example, rocket.rs provides a whole host of different info and links while something like serde.rs covers only examples and documentation.
My solution is a website creation tool that helps standardize information shown based on user data.
Hypotheses & Data
To begin, I wrote a survey designed to gauge user wants and habits when visiting external documentation websites. Questions were based on several hypotheses:
- Non-American users will have a greater desire to utilize internationalization tools.
- Most people use external documentation sites for learning a new resource, but rely on generated docs for everything else
- Most people want repository links up-front
- The first thing visitors want to see is a quick introduction or example of the library or application in use
- Maintainers of larger products are more likely to create external documentation sites
- Most maintainers are looking for a quick solution to generate an external documentation site at the expense of customization
I think these still hold up pretty well, especially the part about library examples.
Data
A small form composed of several questions related to my hypotheses were linked to relevant spaces such as The Rust User Forums and the Official Rust Subreddit. I left my form up for several days to make sure users from all time zones had a chance to answer. Here's what I found:
Before we go on to questions, a card sort activity would be a great fit for this research (and is sometimes more engaging than a simple survey). If I ever revisit this project, I'll try it out and adjust priority and grouping as a result.
It might look something like this:
How are current solutions?
Q: How do you view the usefulness of documentation websites separate from generated docs (such as rocket.rs or hyper.rs)?
The majority of external documentation websites are happily received, with a plurality of users commenting that they are most useful when first learning a library or application.
The scope of this project should not intersect with Rust's generated docs - so although many users say that these websites are useful through all stages of development, we will not focus on creating another generated documentation system.
What do users look for?
Q: What do you look for when reading an external documentation site?
What do users look for? (contd.)
Q: What resources do you expect to be featured/important on documentation sites? Note: this question is more open-ended than the last, and asks for a user's desired features. Participants chose up to 4 answers.
What did users dislike about current solutions?
Q: What do you think current external documentation sites do incorrectly?
While a useful question, this is giving users the responsibility of the designer. A better method would be to watch a user interacting with a prototype or existing product.
What developers want it?
Q: Have you or do you plan to create an additional website with documentation separate from generated docs?
A plurality of Rust users do not believe their application or library needs an external documentation site. This is expected, as the effort put into creating a website is usually only reserved for larger projects.
My focus is on users who are considering a website, or feel as though a website requires too much effort to set up.
What do developers want?
Q: If you were to create a separate documentation site, what would be the most important features when developing?
Participants picked their top 3 choices. Ease of use, documentation, and visual design are the most important to users surveyed.
What do developers want? (contd.)
Q: What is more important to you when creating a documentation site?
A vast majority of participants agree that an external documentation site should be easy to set up, even at the cost of customizability. Although a compromise can be made between the two qualities, I forced participants to choose between the two in order to better gauge their needs.
Summary
Programmers want something easy to set up and maintain.
- Some participants don't feel as though they have enough time to create a dedicated website
- "Ease of use" is voted the most wanted feature
- Participants prefer ease of use over customizability
Users want examples and quick info.
- Example code is heavily desired website info, with many users disliking websites with incomplete examples
- Quick summaries of the project are a must
- External links such as to GitHub should be readily visible
What I learned
- Examples are most important. Users want to see what the library or application does right off the bat, and how they can utilize it in their own projects.
- The biggest complaint about external documentation sites is incomplete information. I can push authors in the right direction by making a tool that focuses on ease of use and maintainability.
- Ease of use is most important to authors. They are willing to sacrifice some customization for a quick solution.
- Design matters. It's a common misconception within some facets of the software community that visual design is unimportant. I was happy to see that Rust users still value the importance of good UI and UX.
- Internationalization seems like it is not a huge concern, but that is not necessarily true. This is due to the survey being written in English and being posted on mostly English forums.
What I did wrong
There's a few things I wish I did differently with this survey.
- Focus on disabilities, especially vision problems. While any good design should have proper contrast and sizing, understanding how to best serve everyone is important.
- Include non-English communities. This survey was posted on overwhelmingly English forums, which skewed internationalization opinions. It would have been wise to team up with others who could translate the survey into other languages.
Raw data
The above data is just a selection of the questions asked. If you like, you can download a CSV of the responses.
