archive-website
archive-website copied to clipboard
eslint
Improve information architecture of site
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.)
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.
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 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/
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.
In case it is helpful for you to know about me:
- 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.
- 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.
Sounds good on both counts. :) I think @ilyavolodin may be the most passionate about doing this, so I'd defer to his thoughts.
@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.
@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.
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.
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. :open_mouth:
This is part of why OSS is so fun to work on. Small changes can have a large reach/impact.
@IanVS Congratulations 👏 That is leverage 💪
What are your thoughts about strengths to keep intact and problems to solve in ESLint website?
@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.
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.
Related to the idea of a tutorial to set up and configure ESLint mentioned in https://github.com/eslint/eslint.github.io/issues/186#issuecomment-176457525 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?
@xjamundx Started doing that at some point, but I'm not sure when/if he stopped.
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 https://github.com/eslint/eslint.github.io/issues/186#issuecomment-187487983 .
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
.eslintrcfile - ES6 supports
- autofixing basic errors
- ??
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.
Oh and here's the list of other potential topics:
globalvslocalinstall- comment configuration
- editor integrations
- task runners
- formatters
- select plugins (react, angular, etc.)
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.
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.
no-multi-spaces with the current layout has a gap above the first code well:
no-multi-spaces with the proposed layout displays more information above the fold:
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).