Rust Docs

2018-05-28

Synopsis

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.

Project Type

ui/ux, web

Timeframe

2 weeks


Work in Progress

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.

Background

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.

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:

  1. Non-American users will have a greater desire to utilize internationalization tools
  2. Most people use external documentation sites for learning a new resource, but rely on generated docs for everything else
  3. Most people want repository links up-front
  4. The first thing visitors want to see is a quick introduction or example of the library or application in use
  5. Maintainers of larger products are more likely to create external documentation sites
  6. Most maintainers are looking for a quick solution to generate an external documentation site at the expense of customization

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:

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?


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.

  1. Some participants don't feel as though they have enough time to create a dedicated website
  2. "Ease of use" is voted the most wanted feature
  3. Participants prefer ease of use over customizability

Users want examples and quick info.

  1. Example code is heavily desired website info, with many users disliking websites with incomplete examples
  2. Quick summaries of the project are a must
  3. External links such as to GitHub should be readily visible

What I learned

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:

  1. Internationalization is not a huge concern, despite receiving responses from all over the globe. However, this is possibly due to the survey being written in English and being posted on mostly English forums.
  2. 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.
  3. 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.
  4. Ease of use is most important to authors. They are willing to sacrifice some customization for a quick solution.
  5. 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.

What I did wrong

There's a few things I wish I did differently with this survey.

  1. Focus on disabilities, especially vision problems. While any good design should have proper contrast and sizing, understanding how to best serve everyone is important.
  2. Include non-English communities. This survey was posted on overwhelmingly English forums, which may have 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.

Design

Wireframes are coming soon! Stay tuned.