The Rust Language needs a better way to create external documentation websites. I use a data-based approach to determine the victories and pitfalls of current solutions.
This project is still in the works, so please remember that the following is not representative of a final product! Descriptions and fine details may be absent. With that said, take a look.
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.
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.
To begin, I wrote a survey designed to gauge user wants and habits when visiting external documentation websites. Questions were based on several hypotheses:
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:
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.
Q: What do you look for when reading an external documentation site?
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.
Q: What do you think current external documentation sites do incorrectly?
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.
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.
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.
As a disclaimer, I'm a designer - not a statistician. I interpret these numbers to the best of my abilities, but it is possible that I'll make an error. With that said, here's what I've learned from the survey:
There's a few things I wish I did differently with this survey.
The above data is just a selection of the questions asked. If you like, you can download a CSV of the responses.
Wireframes are coming soon! Stay tuned.