Improve information architecture of site

[nzakas]

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.)

[ilyavolodin]

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]

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]

@pedrottimark and what would be the solution?

[pedrottimark]

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

• Make it easier to scan the lists in http://eslint.org/docs/rules/

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]

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]

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]

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

[ilyavolodin]

@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]

@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]

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]

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]

@IanVS Congratulations 👏 That is leverage 💪

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

[IanVS]

@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]

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]

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]

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

[xjamundx]

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 notifications@github.com
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]

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]

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]

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]

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]

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]

comma-dangle is recommended:

[pedrottimark]

no-multi-spaces is fixable:

[pedrottimark]

no-extra-semi is recommended and fixable:

[pedrottimark]

no-extra-parens is neither recommended nor fixable:

[pedrottimark]

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

[pedrottimark]

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

[pedrottimark]

Most rules under Possible Errors have icons:

[ilyavolodin]

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]

Few rules under Best Practices have icons:

[pedrottimark]

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

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

[ilyavolodin]

@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]

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.