Skip to content
This repository has been archived by the owner on Nov 10, 2022. It is now read-only.

Improve information architecture of site #186

Open
nzakas opened this issue Jan 27, 2016 · 34 comments
Open

Improve information architecture of site #186

nzakas opened this issue Jan 27, 2016 · 34 comments
Labels
documentation Relates to ESLint's documentation enhancement This change enhances an existing feature of the website

Comments

@nzakas
Copy link
Member

nzakas commented Jan 27, 2016

The information architecture we have at present is mostly an accident of how our folders were setup initially. There was only a small amount of thought put into how best to organize the documentation, as we just wanted to write as much documentation as possible without worrying about the best way to present it.

Now that we have a massive amount of documentation, we could really use some help figuring out better ways of organizing it. Any and all recommendations welcome! (Be gentle, the team doesn't have any information architecture experience or knowledge.)

@nzakas nzakas added the enhancement This change enhances an existing feature of the website label Jan 27, 2016
@ilyavolodin
Copy link
Member

Some of the things to look into would be to break up large articles like http://eslint.org/docs/developer-guide/working-with-rules into smaller pages, or provide internal navigation through them. Make configuration options more prominent and easier to find.
Also, keep in mind that majority of our documentation is auto-generated from .md files, so we don't always have full control over layout and structure of the output.

@pedrottimark
Copy link
Member

Example of a simple inconsistency which pushes me out of the flow a bit each time I learn a new rule:

http://eslint.org/docs/rules/ has rule string as hyperlink text followed by hyphen and rule description in all lowercase, for example:
comma-dangle - disallow or enforce trailing commas

http://eslint.org/docs/rules/comma-dangle heading has rule description in title case followed by rule string in parentheses, for example:
Disallow or Enforce Dangling Commas (comma-dangle)

@nzakas
Copy link
Member Author

nzakas commented Jan 28, 2016

@pedrottimark and what would be the solution?

@pedrottimark
Copy link
Member

@nzakas Hello! Here are 2 examples of tactical goals and possible changes to achieve them:

Move icons (for recommended and fix) from the end to beginning of line, possibly as columns of tables (without borders) instead of the bulleted lists.

Simplify punctuation (especially because rule strings contain hyphens) possibly use some white space separation, but not separate columns.
comma-dangle: disallow or allow trailing comma

  • Make a clearer visual connection between cause and effect when you click a rule link, and then see heading on destination page.

Heading of rule page has same text as line in rule list, but different style, of course.
comma-dangle: disallow or allow trailing comma

If the icons are important enough on the rule page (pending analysis, see below) maybe hang them in the margin at the left of the heading. Provide screen tip via title attribute. If there is enough supplementary information, the icons are hyperlinks to pages about recommended and fix.

Does that help? What do you think about the problem-solving method? And the specifics, of course?

Can you compare and contrast your vision as owner to the following possible way forward: a team of people (who respond to the call) use a consensus of methods to review interior content; evaluate according to heuristics; discuss, prioritize, and design improvements.

For example:
http://www.uxbooth.com/articles/make-design-decisions-with-a-purpose/
https://www.nngroup.com/articles/how-to-conduct-a-heuristic-evaluation/

@nzakas
Copy link
Member Author

nzakas commented Jan 28, 2016

That's very helpful, thanks. I agree that those seem like excellent goals for the page.

As for my vision as owner, I'm perfectly happy to delegate this completely. The team feels, in general, that the content isn't organized well enough right now. That's not something we can quantify, but we get periodic feedback and we try to make things better (for instance, I don't think anyone is happy with the organization of rule documentation, both the index and individual rule pages...we just don't know what else to do). However, that's very reactive and I think we'd all like to be a bit more proactive at this point. Doing a whole evaluation to see what people uncover would be great.

@pedrottimark
Copy link
Member

In case it is helpful for you to know about me:

  1. I prefer to find clarity, consensus, and confirmation on problem analysis (who, what, when, where, why) before going too deeply into problem solution (how) both to prioritize and give space for alternatives. You might say I work middle-out with that balance instead of top-down or bottom-up.
  2. I lean more to applying available relevant solid principles of user experience (both by temperament and because of resource limitations) than empirical methods like interviewing, surveying, and usability testing. Some people who respond to the community call might bring strength in those valuable areas.

@nzakas
Copy link
Member Author

nzakas commented Jan 28, 2016

Sounds good on both counts. :) I think @ilyavolodin may be the most passionate about doing this, so I'd defer to his thoughts.

@ilyavolodin
Copy link
Member

@pedrottimark The way I see it, most of the people who will visit website are looking for either information about rules, or information about how to install/configure eslint in general. Small portion of population is going to be looking into creating plugins/shareable configs.
Right now, rules documentation is easy to find, but each rule has a slight difference in formatting and it's hard to find all of the available options and what they mean. It's also pretty much impossible to find which rule should I enable to enforce space between object keys, for example.
Documentation for setting up/configuring ESLint is much harder to find and it's also very long. I would love to see 5-10 easy step tutorial that can provide more information on each step if necessary.
API documentation is just very long. It's a wall of text that's pretty hard to read, and not easy to find information you are looking for.

There are also a few gotchas in ESLint that screw up a lot of users, one being local vs. global install, the other one numerical values for off/warning/error. While both of those are noted in the documentation, they do not immediately jump out, and we get a lot of issues regarding those two.

In general, I would love to see a unified template for rule documentation, and some better way to break up longer articles. Also beginners guides.

Let me know if you would like me to get some analytic data for page visits for specific pages, this would probably help determine what people are looking for and how to make it easier to find.

P.S. I completely agree on using principles of user experience instead of testing/interviewing/etc. Those things, while very helpful, take a ton of time and not very suitable for OSS.

@pedrottimark
Copy link
Member

@ilyavolodin That is a great list of pain points (well, you know what I mean). Yes, please do get some analytic data. For extra credit, think about what data to get now to allow some kind of basic before and after comparison of improvement in the experience using the site.

@ilyavolodin
Copy link
Member

So here's some of the analytic data that I was able to pull from September 30th, till today:

Total number of sessions: 282389
New Sessions: 42.02%
Avg. Session Duation: 4m 51s
Avg. Pages / Session: 3.30

Top Landing pages:

URL Total Sessions New Users
/ 27.85% 62.34%
/docs/user-guide/configuring 19.42% 62.16%
/docs/rules/integrations 1.79% 44.02%
/docs/rules/indent 1.68% 39.56%

Top pages:

URL Pageviews Avg. Time on Page
/docs/rules 136804 1m 2s
/ 114098 1m 13s
/docs/user-guide/configuring 128641 4m 15s
/docs/user-guide/getting-started 24257 3m 15s
/docs/user-guide/command-line-interface 14242 3m 44s

I will add more basic data tomorrow. Let me know if you want to see something specific.

@IanVS
Copy link
Member

IanVS commented Jan 29, 2016

It's silly, but it feels pretty good to see that a page I threw together (getting started) is the fourth most visited on the site, with nearly 25,000 views. 😮

This is part of why OSS is so fun to work on. Small changes can have a large reach/impact.

@pedrottimark
Copy link
Member

@IanVS Congratulations 👏 That is leverage 💪

What are your thoughts about strengths to keep intact and problems to solve in ESLint website?

@IanVS
Copy link
Member

IanVS commented Feb 1, 2016

@pedrottimark I think @ilyavolodin already covered all of my thoughts. I would really like to see a standard format for rule docs, and I think all pages should have some kind of Table Of Contents at the top to ease navigation and provide a clear mental modal for readers approaching the page for the first time. I like the way Babel handles this by putting it in the right sidebar. The amount of inconsistency we have in the docs is a little bit ironic, considering we are a tool for increasing consistency.

We also need to make sure that whatever we do, we don't make it difficult to edit or contribute to the docs. We get a good number of PRs from first time contributors for doc fixes (which is a great way for people to jump in and help out), and updates to the docs are also required when adding or updating a rule or API. So, we can't make it difficult to contribute to the docs, or people will give up.

@ilyavolodin
Copy link
Member

Some more data for the same period of time:

Top exit pages for long sessions (>1 minute):

url % exit avg session duration avg time on page avg pages per session
/docs/user-guide/configuring.html 53.34% 00:04:33 00:04:16 1.68
/ 32.44% 00:04:39 00:01:13 1.45
/docs/user-guide/configuring 40.87% 00:04:59 00:03:38 5.23
/docs/rules/ 14.21% 00:07:19 00:01:00 5.88
/docs/user-guide/getting-started 44.12% 00:02:34 00:03:12 12.03
/docs/user-guide/command-line-interface 40.98% 00:04:59 00:03:38 6.90

Technology:

Desktop: 93.06%
Mobile: 5.55%
Tablet: 1.39%

Clicks on the homepage:

Getting Started Button: 25%
Logo: 8.8%
User guide menu: 8.8%
Developer guide menu: 8.8%
Blog menu: 1.5%
Demo menu: 8.8%
About menu: 7.4%
CLI Details button: 6.2%
Rules See List button: 18%
Start Hacking button: 2.0%

Unfortunately, we do not track search terms, as search have only been added recently to the site. I'll open another issue to add that in.

@pedrottimark
Copy link
Member

Related to the idea of a tutorial to set up and configure ESLint mentioned in #186 (comment) someone recently suggested videos to me. Made me think of the 30 short lessons on egghead about Redux. Any thoughts who (not limited to core team) might rise to the challenge the way Dan Abramov did?

@ilyavolodin
Copy link
Member

@xjamundx Started doing that at some point, but I'm not sure when/if he stopped.

@xjamundx
Copy link

I'll do a series for you guys. I need to make some for work anyway.

On Mon, Feb 22, 2016 at 6:19 PM Ilya Volodin [email protected]
wrote:

@xjamundx https://github.com/xjamundx Started doing that at some point,
but I'm not sure when/if he stopped.


Reply to this email directly or view it on GitHub
#186 (comment)
.

@xjamundx
Copy link

Can anyone suggest a video to start with and i'll try to do it today? 2 min on anything.

  • Installing eslint
  • eslint --init
  • Installing a style guide
  • Customizing your .eslintrc file
  • ES6 supports
  • autofixing basic errors
  • ??

@ilyavolodin
Copy link
Member

eslint --init can be split up into multiple short lessons. One for autoconfig, one for styleguide, one for answering questions.
Then you can select a topic, like whitespaces around functions and describe all of the rules that deal with that topic.

@ilyavolodin
Copy link
Member

Oh and here's the list of other potential topics:

  • global vs local install
  • comment configuration
  • editor integrations
  • task runners
  • formatters
  • select plugins (react, angular, etc.)

@pedrottimark
Copy link
Member

A good way to prioritize is whether something is painful-not-to-know instead of nice-to-know.

A good goal is for people with beginning-to-intermediate level of experience to feel after viewing: I could do that.

@pedrottimark
Copy link
Member

The following comments have pictures for your feedback about layout at the top of rules pages.

While my mental slow cooker works on the CSS, y’all correct (or revoke :) these visual usability goals:

  • Display recommended and fixable icons in a predictable place so they are easy to find (or ignore).
  • Limit line length to improve readability and make a margin for the ad. Get rid of a distracting gap above the first code example in some pages. Make a place for possible table of contents.
  • Adjust layout of rules list so recommended and fixable icons are easy to find. Also for a clearer visual transition from a list item to the corresponding rule page.

@pedrottimark
Copy link
Member

comma-dangle is recommended:

comma-dangle_recommended

@pedrottimark
Copy link
Member

no-multi-spaces is fixable:

no-multi-spaces_fixable

@pedrottimark
Copy link
Member

no-extra-semi is recommended and fixable:

no-extra-semi_recommended_fixable

@pedrottimark
Copy link
Member

no-extra-parens is neither recommended nor fixable:

no-extra-parens

@pedrottimark
Copy link
Member

no-multi-spaces with the current layout has a gap above the first code well:

no-multi-spaces_layout-current

@pedrottimark
Copy link
Member

no-multi-spaces with the proposed layout displays more information above the fold:

no-multi-spaces_layout_proposed

@pedrottimark
Copy link
Member

Most rules under Possible Errors have icons:

rules_dense

@ilyavolodin
Copy link
Member

Nice. Although I'm not sure checkmark next to the name of the rule is going to be self-explanatory (on the rule's page).

@pedrottimark
Copy link
Member

Few rules under Best Practices have icons:

rules_sparse

@pedrottimark
Copy link
Member

That is the kind of “new eyes” feedback this needs!

Here the introduction to the list with recommended and fixable as bulleted items:

rules

@ilyavolodin
Copy link
Member

@pedrottimark Sorry, I think on the index page, icons are fine, since we have an intro at the top. However, on a given rule page, there is no explanation of what those icons mean. Fixable icon is right next to the paragraph that explains that this rule is fixable, so it should be fine, but checkmark is next to the name of the rule, without any explanation, so it might be tough for a user to figure out what it means. Maybe we can do alt text on the icon, but it would be nice it you wouldn't have to mouse over it to figure out why it's there.

@pedrottimark
Copy link
Member

Yes, at first glance it seemed “asymmetrical” for a rule page to display fixable but not recommended. But out of the context of the list, ESLint-recommended might even mislead people who use packaged configurations like eslint-config-airbnb. So now you mention it, I lean toward omitting it from the redesign.

Maybe we can take a few Twitter polls to understand how people are using ESLint and who needs what kind of technical information.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
documentation Relates to ESLint's documentation enhancement This change enhances an existing feature of the website
Projects
None yet
Development

No branches or pull requests

6 participants