docs!: Docs information architecture refactor

[bpmutter]

Summary

This document contains proposed changes to the information architecture in the ESLint documentation website, https://eslint.org/docs.

On a high level, the proposed information architecture breaks the content into the following sections:

• Use ESLint in Your Project: A refactor of the current User Guide
• Extend ESLint: A refactor of the current Developer Guide, with some content moved to the section Maintain ESLint and Community Contributions
• Maintain ESLint: Expansion of current Maintainer Guide, with some content taken from the current ‘Developer Guide’.
• Community Contributions: Expansion of the current Contributing section of the Developer Guide.

Related Issues

eslint/eslint#16365

[eslint-github-bot]

Hi @bpmutter!, thanks for the Pull Request

The first commit message isn't properly formatted. We ask that you update the message to match this format, as we use it to generate changelogs and automate releases.

• The commit message tag wasn't recognized. Did you mean "docs", "fix", or "feat"?
• There should be a space following the initial tag and colon, for example 'feat: Message'.
• The first letter of the tag should be in lowercase

To Fix: You can fix this problem by running git commit --amend, editing your commit message, and then running git push -f to update this pull request.

Read more about contributing to ESLint here

[eslint-github-bot]

Hi @bpmutter!, thanks for the Pull Request

The first commit message isn't properly formatted. We ask that you update the message to match this format, as we use it to generate changelogs and automate releases.

• The commit message tag wasn't recognized. Did you mean "docs", "fix", or "feat"?
• There should be a space following the initial tag and colon, for example 'feat: Message'.
• The first letter of the tag should be in lowercase

To Fix: You can fix this problem by running git commit --amend, editing your commit message, and then running git push -f to update this pull request.

Read more about contributing to ESLint here

[nzakas]

Thanks for putting this together. I left a few comments.

It would also be helpful to include a simplified new documentation index that is just bullets and sub-bullets that shows the intended complete view of the left side of the docs. It’s a little difficult to envision it from the way this is structured currently.

[bpmutter]

t would also be helpful to include a simplified new documentation index that is just bullets and sub-bullets that shows the intended complete view of the left side of the docs. It’s a little difficult to envision it from the way this is structured currently.

sure will add

[bpmutter]

@nzakas responded to and implemented your feedback!

[nzakas]

@bpmutter Hmmm, I’m not seeing any changes, did you push your latest commit?

[bpmutter]

@bpmutter Hmmm, I’m not seeing any changes, did you push your latest commit?

@nzakas sorry, didn't push yesterday. just did now. you can find the content there.

[bpmutter]

@mdjermanovic responded to your feedback!

[nzakas]

TSC Summary: The last point to address here is how to move forward with URL structure. Possible options are 1) persona/action such as users/configure, 2) use case/action such as use/configure, 3) using/configuring

TSC Question: Which format do we want to use?

[mdjermanovic]

In yesterday's TSC meeting we agreed to use /:verb/:subject for the URL format. In the options above, that's "2) use case/action such as use/configure".

If any path looks weird with this format, we can consider changing its URL by changing the :subject part (e.g., /integrate/nodejs-api could be /integrate/using-api), or by inserting /learn/ in the middle (e.g., contribute/architecture could be contribute/learn/architecture), or in some other way so that it reads better.

[bpmutter]

In yesterday's TSC meeting we agreed to use /:verb/:subject for the URL format. In the options above, that's "2) use case/action such as use/configure".

thank you for the update! i'll update the URL paths to follow this pattern. will let the TSC know when that's done.

[bpmutter]

ok, @nzakas i believe i have updated the URL paths in all parts where it was necessary. also did final review for copy changes, and everything seems to be ready for (final?) re-review.

[nzakas]

I think we are in pretty good shape now. Moving to final commenting.

[bpmutter]

@mdjermanovic ready for re-review

[mdjermanovic]

Looks good to me! Great idea to reorient around the core personas and split the Developer Guide into Contribute to ESLint and Extend ESLint.

[nzakas]

All right, it looks like we are ready to move forward with this. Thanks everyone!