Eslint: Google Season of Docs participation

[nzakas]

The Google Season of Docs program is coming up again in 2020, and I'd like to see what people think about participating?

https://developers.google.com/season-of-docs/docs

Two questions:

1. Do we want to participate?
2. What documentation projects should we apply for?

The application process starts April 13, 2020 so we should try to make a decision soon.

[nzakas]

I'd like to put together an in-depth getting started guide that goes through:

1. Installing ESLint in a project
2. Setting up a configuration file
3. Creating an npm script to run ESLint
4. Modifying a configuration file
5. Anything else that makes sense after this point (feedback welcome)

[kaicataldo]

Building on your suggestion, adding some documentation around common use cases (TypeScript, Babel, Vue, integrating with Prettier, etc.) would be helpful as well. Prettier's documentation does a good job of this (see https://prettier.io/docs/en/precommit.html and https://prettier.io/docs/en/integrating-with-linters.html) and I've personally found it be very helpful when setting up my own projects.

One other project that would provide a lot of value for our users would be to reorganize the "Configuring ESLint" page into easier to digest sections (potentially split across multiple pages).

[nzakas]

As the deadline is quickly approaching, I suggest we focus on the configuration page as our submission. Any objections?

[SanketDG]

Hi, new here. I'd be interested to participating in this.

Where can I pick up some low hanging tasks?

[nzakas]

@SanketDG thanks! We've not done a good job of organizing existing documentation tasks, so I'm afraid I can't point you to anything. We're using this issue to discuss how we want to submit to Google Season of Docs. If you've noticed anything that can be improved in our docs, please open an issue (or two) to let us know and we can guide you on how to fix things.

[nzakas]

Final Project List for Season of Docs

Project: ESLint
Website: https://eslint.org

1. A new getting started guide

Our current getting started guide doesn't provide a lot of detail for new users. Ideally, we'd have a guide that could walk people through:

1. Installing ESLint
2. Configuring ESLint
3. Creating an npm script to run ESLint
4. Interpreting ESLint results
5. Automatically fixing ESLint problems
6. Extending/overriding configurations
7. Integrating into a CI environment

References:

• Getting started with ESLint - current guide

2. Reorganize/rewrite configuration documentation

All of our configuration documentation is currently on one page. This covers every part of configuring ESLint and is difficult to follow and a bit overwhelming. We'd like to get this page split up into multiple pages and better organized so users can find the information they need without swimming through every configuration option in ESLint first.

References:

• Configuring ESLint - current guide

3. Common tasks documentation

One thing we have definitely been lacking is a set of tutorials for common tasks. While there are pieces of information strewn about on eslint.org, we don't have a lot of task-focused tutorials that walk people through common tasks. Some common tasks we'd like to cover:

1. Creating a shareable config (either standalone or in a plugin)
2. Creating and using a custom rule
3. Creating a processor
4. Creating a formatter
5. Packaging and distributing custom rules/processors in a plugin
6. Setting up a development environment for ESLint

References:

• Working with rules
• Working with plugins
• Working with formatters

4. New rule page format

We have over 300 rules that each have a page of documentation. The format of the rule documentation page is something we've struggled with as we've tried to balance describing every option with readability, knowing that people don't want to read a ton of docs just to configure a rule. We really need a new format for each rule documentation page that can provide some consistency and uniformity without overloading users. This project would be to come up with a new format and then rewrite each rule's documentation page to match the format.

References:

• ESLint rules list

[math-alpha]

Greetings @nzakas I would like to contribute to Eslint through the GSoD program.
I will like to work on the "Common tasks documentation" project.
Looking forwards for guidance and in the meantime, I will be working on some issues. Thanks

[pankajparashar]

I have never used ESLint before, but I'm willing to try so that I can offer a beginner perspective on what part of the docs were useful in getting me started with the library and what part needs to be improved.

Off the shelf, before I begin to use any lint-rule library, I have three questions in my mind,

1. How to install the library?
2. How to add/configure new lint rules?
3. How to integrate it in my development workflow?

I feel like the getting started page does a good job of answering #1 but wasn't helpful in answering #2 and #3. Maybe when I spend more time reading the docs, I'll get those answers.

For advanced usage, I am wondering,

1. How do I define my own custom rules?
2. How do I enable/disable specific rules for specific scripts?
3. Can I share my lint rules with other developers?

Disclaimer: I'm coming from a Python background where I've used pylint for the major portion of my dev career. Some of the questions that I've listed may not be relevant to node.js. But I think it'll be a helpful exercise.

[nzakas]

Thanks, everyone, for your interest! Please take a moment to read over the technical writer guidelines. Right now, we are here to answer any questions you might have. To officially participate, you’ll need to apply as a technical writer to the Season of Docs program (discussed in the above link).

[swetankraj]

@nzakas For the given project list do I need to select one of them or a participant will be handling all the mentioned requirements in the list?

[nzakas]

To apply, you would select one of the projects in this list and describe your plan for completing it. You can also propose a project not listed that you think would be useful (check out the link in my previous comment for more details).

[swetankraj]

@nzakas thank you. I'll take a look at the link you provided. I'll take a deep look into mentioned projects and do let you know.

Here's something I'd like to add:

1. Spliting up pages into more modular forms. Which results in better structured form.
2. For example, if we take a look at Prettier Docs, the section About has been splitted up into What, Why?, vs, Philosophy and else... I think this really helps new user to understand the product more better. React.js Docs also does the same.
3. Also the inclusion of video and other media types, conferences related to ESLint, would also help. For example, official video walkthrough in the installation page.

[nzakas]

Thanks for the ideas. WRT to video: we’ve found this difficult because they get out of date quickly and we don’t have the cycles to keep making new ones.

[suyashsingh234]

Hello @nzakas
I am Suyash Singh. I would like to participate in GSOD 2020 and would like to work on the project idea "A new getting started guide". I have written on Clang Static Analyzer and LLVM sanitizer before.
What is the correct gitter, channel, etc to communicate regarding my proposal?

[nzakas]

If you have general questions, you can post them on this issue so we can share the answers with everyone. You can also use the mailing list to send in questions that you think might be more specific to your proposal.

[UthpalaPitawela]

Hello @nzakas
I'm Uthpala Pitawela. I would like to participate to Google Season of Docs 2020. I have gone through the project ideas you have mentioned and would like to contribute to "Reorganize/rewrite configuration documentation". I'll come up with some suggestions and ideas for the existing documentation and get your feedback on them. Thank you

[kaicataldo]

Thanks to everyone for the interest. Please feel free to ping me in these discussions going forward, as I’ll be a dedicated mentor for the program this summer. I’ll also respond to questions sent to our mailing list. Excited to make our docs better!

[bandantonio]

Hello @kaicataldo
I would also like to participate in GSoD 2020 and work on the "A new getting started guide" project.
Do I understand correctly that the first step is to join this discussion and share my thoughts on possible improvements?

[kaicataldo]

@bandantonio This part of the process is intended for applicants to speak with participating projects so that they can learn about the organization and the proposed projects and decide which projects to apply for in June.

I’m happy to discuss your ideas over the mailing list!

[AnjaliSharma1234]

Hello everyone!
I am keenly interested in contributing to Google Season of Docs 2020 under ESLint.
@kaicataldo @nzakas How about proposing something new or if I have to discuss my proposal with the organization personally? How would I proceed in such a scenario?

[kaicataldo]

@AnjaliSharma1234 Feel free to ask us questions. The program will require a formal application in June, and this time is intended for those who are interested in participating to discuss with maintainers and see what projects they would like to apply to.

[ani-sha]

Hey, @nzakas @kaicataldo. I would like to take part in Google Season of Docs 2020. Looking forward to getting started :)

[samrobbins85]

Hi all, I'd love to work on the getting started guide, but I'd be very happy working on any section of the documentation

[kaicataldo]

Hey all, while we're thrilled to see so much interest, we would appreciate it if we could keep this issue thread focused on discussions around the projects themselves. There will be a formal application phase (from June 9 - July 9, 2020) where you can express interest and submit an application to participate in Season of Docs.

If you haven't yet, please take a look at the Technical writer guide in the Season of Docs documentation. We are currently in the Technical writer exploration phase, which is intended for those who are interested to explore projects and ideas.

Thanks!

[UthpalaPitawela]

Hi,

I would like to contribute to Google Season of Docs 2020 as a technical
writer. I have gone through the projects ideas. Project idea #2 is to
rewrite the configuration documentation and as far as I have understood
project#1 also has that as a subtask. According to my understanding, both
configurations are related to ESLint. Am I correct or is there any other
configuration document specified in project #2?

Thank you

On Fri, May 15, 2020 at 9:59 PM Kai Cataldo [e-mail]
wrote:

Hey all, while we're thrilled to see so much interest, we would appreciate
it if we could keep this issue thread focused on discussions around the
projects themselves. There will be a formal application phase
https://developers.google.com/season-of-docs/docs/tech-writer-guide#technical_writer_application_phase
(from June 9 - July 9, 2020) where you can express interest and submit an
application to participate in Season of Docs.

If you haven't yet, please take a look at the Technical writer guide
https://developers.google.com/season-of-docs/docs/tech-writer-guide in
the Season of Docs documentation. We are currently in the Technical
writer exploration phase
https://developers.google.com/season-of-docs/docs/tech-writer-guide#tech-writer-explore,
which is intended for those who are interested to explore projects and
ideas.

Thanks!

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/eslint/eslint/issues/13130#issuecomment-629356448,
or unsubscribe
https://github.com/notifications/unsubscribe-auth/AEIFIRAC4KJC6FPKJPGQG73RRVUXNANCNFSM4LZKPDIQ
.

[kaicataldo]

Thanks for your interest. Project 1 and 2 are separate tasks that don't overlap. The goal of Project 1 is to create a better "Getting Started" or onboarding guide for new ESLint users. The goal of Project 2 is to come up with a way to make the full configuration docs easier to navigate and understand.

[sharmaaditya570191]

Hello everyone!
I am Aditya Sharma. I am currently working as a student developer on a web based open source project in Google Summer of Code 2020. I work on various technologies like Node.js , React , Headless CMS based on Node.js (Strapi) and GraphQL. ESLint is something which I have used from the very beginning and have seen it grow. I am really interested in working on setting up a new getting started guide for ESLint as I have seen many new users getting stuck at various points. Please let me know how I can contribute towards the project during this time @kaicataldo . Thanks.

[UthpalaPitawela]

Hi,

When configuring ESLint, don't we need to mention prerequisites? Is it
enough to have them only on 'getting started'? Looking forward to your
response.

Thanks

On Sun, May 17, 2020 at 11:09 PM Aditya Sharma [e-mail]
wrote:

Hello everyone!
I am Aditya Sharma. I am currently working as a student developer on a web
based open source project in Google Summer of Code 2020. I work on
various technologies like Node.js , React , Headless CMS based on Node.js
(Strapi) and GraphQL. ESLint is something which I have used from the very
beginning and have seen it grow. I am really interested in working on
setting up a new getting started guide for ESLint as I have seen many new
users getting stuck at various points. Please let me know how I can
contribute towards the project during this time @kaicataldo
https://github.com/kaicataldo . Thanks.

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/eslint/eslint/issues/13130#issuecomment-629834136,
or unsubscribe
https://github.com/notifications/unsubscribe-auth/AEIFIRFAWHMOULLSH4DZZGLRSAOOTANCNFSM4LZKPDIQ
.

[sayak119]

Hi everyone!
I am Sayak Kundu. I would like to contribute to Google Season of Docs 2020 as a technical writer. I am interested in Project 1 (A new getting started guide). I have worked with the Internet Archive for past 1 year on their Google Action and Alexa Skill as a developer and this job also required me to write technical reports. I have experience with ESLint along with other frameworks. I would like to contribute back by improving the Getting Started guide. I would very much like to know about the steps involved further for contributing to this guide @kaicataldo @nzakas .

[nzakas]

@UthpalaPitawela Yes, the only prerequisite is to have Node.js installed. Because Node.js comes with npm, you can then use npm to install ESLint.

[nzakas]

Hi everyone,

Just to reiterate, this period is for prospective technical writers to learn about ESLint and ask questions to clarify what the project is looking for. Please see the Season of Docs timeline:

https://developers.google.com/season-of-docs/docs/timeline

If you have questions about how to apply to work on ESLint for Season if Docs, please see the technical writer guide:

https://developers.google.com/season-of-docs

Thanks for your interest!

[JackieBinya]

Hello I'm Jacqueline 🙋🏾‍♀️
What technology or tools was used to build the ESLint Documentation?
I'm particularly interested in project number 2, am I able to submit my proposal now or soon rather so that we may discuss ideas I have at the moment?

[nzakas]

Here’s a good article about the Season of Docs program:
https://www.freecodecamp.org/news/cracking-google-season-of-docs-2020/

[nzakas]

@JackieBinya the documentation is stored in Markdown files in this repo (the docs directory). We then use a build process to publish them on the website. This happens automatically, so you would just need to feel comfortable working with Markdown files.

Please see the links I provided in my previous comment for more details about the timing of submissions.

[JackieBinya]

Thank you for the clarification @nzakas
Well in the past I have written blog tutorials on several topics as exemplified by this tutorial Joi Tutorial-Using @hapi/joi version 16.1.7 to validate a request body in a RESTful API
@hapi/joi is an npm module

Well in my previous writing experiences I didnt have any restrictions or limitations in coming up and presenting content. My goal has always been to be detailed, resourceful as well as engaging to the reader and I think I perform fairly well in that regard.
Now my question if I am tasked with writing a tutorial for eslint organization, how am I expected to come up with the content? Do I have deliberations with other devs and writers within the organization to come up with the content. Or conversely I am expected to familiarize myself with product and come up with the content on my own as long as I stick to the suggested structure?

Normally what is the content creation process like?

[nzakas]

@JackieBinya we would like you to become familiar with the project, and then we will work with you to come up with content ideas that you would then expand into full documentation. You’ll work with a mentor on the team (@kaicataldo) who will guide you through the process.

[nzakas]

Hi everyone, we’ve started a season of docs channel in our Discord server to answer questions about the ESLint project and our suggested Season of Docs projects. You can visit by going to https://eslint.org/chat

[dillionmegida]

Final Project List for Season of Docs

Project: ESLint
Website: https://eslint.org

1. A new getting started guide

Our current getting started guide doesn't provide a lot of detail for new users. Ideally, we'd have a guide that could walk people through:

1. Installing ESLint
2. Configuring ESLint
3. Creating an npm script to run ESLint
4. Interpreting ESLint results
5. Automatically fixing ESLint problems
6. Extending/overriding configurations
7. Integrating into a CI environment

References:

• Getting started with ESLint - current guide

2. Reorganize/rewrite configuration documentation

All of our configuration documentation is currently on one page. This covers every part of configuring ESLint and is difficult to follow and a bit overwhelming. We'd like to get this page split up into multiple pages and better organized so users can find the information they need without swimming through every configuration option in ESLint first.

References:

• Configuring ESLint - current guide

3. Common tasks documentation

One thing we have definitely been lacking is a set of tutorials for common tasks. While there are pieces of information strewn about on eslint.org, we don't have a lot of task-focused tutorials that walk people through common tasks. Some common tasks we'd like to cover:

1. Creating a shareable config (either standalone or in a plugin)
2. Creating and using a custom rule
3. Creating a processor
4. Creating a formatter
5. Packaging and distributing custom rules/processors in a plugin
6. Setting up a development environment for ESLint

References:

• Working with rules
• Working with plugins
• Working with formatters

4. New rule page format

We have over 300 rules that each have a page of documentation. The format of the rule documentation page is something we've struggled with as we've tried to balance describing every option with readability, knowing that people don't want to read a ton of docs just to configure a rule. We really need a new format for each rule documentation page that can provide some consistency and uniformity without overloading users. This project would be to come up with a new format and then rewrite each rule's documentation page to match the format.

References:

• ESLint rules list

Hi @nzakas, it seems you have a broken link in ESLINT rules list. I think it should be /docs/rules.

[kaicataldo]

Thank you! I have edited the link.

[iMichaelOwolabi]

Awesome! I first knew about ESLint in 2018 during a bootcamp which was a prerequisite for my software development job at the time. I so much loved it that I wrote about it here https://medium.com/@iMichaelOwolabi/cool-tools-i-encountered-as-i-prepare-for-bootcamp-8c5ed0ae45d5

I am definitely sending out my application to contribute to this awesome project.

[nzakas]

@iMichaelOwolabi awesome, we look forward to reviewing your proposal!

[nzakas]

Hi everyone, just as a heads up you can now start applying for Season of Docs projects! Please be sure to review the technical writer guide:
https://developers.google.com/season-of-docs/docs/tech-writer-guide

And then you can apply to the program at this link:
https://bit.ly/gsod-tw-app

[bhutraraghav]

Hi Everyone, I'm Raghav.
I'd learnt web development few months back for a project, While applying JavaScript I got many errors in the beginning. It would have been great if I would have known about ESlint back then. I'll be submitting my idea for improving the documentation of ESlint in my proposal.
looking forward to contribute for the documentation for ESlint.

[DAMMAK]

Hi, everyone I'm FullStack Javascript Developer, I'm very interested and want to participate in the Eslint project in Google Season of Docs.. I wrote an article on ESLINT last year... I will like to choose project 4 New rule page format

article link below:
https://blog.dammak.dev/setting-up-eslint-in-your-javascript-project-with-vs-code-cjzh1djzf004vlcs11jpo379d

[iMichaelOwolabi]

@nzakas Please, which tool was used in creating the current documentation? Are there any preferred tools in mind that the team is already considering for documentation?

Thanks

[kaicataldo]

@iMichaelOwolabi Please see this comment above.

I don't foresee us changing how we currently create the documentation and build the site - since this is a pretty standard way of doing things in the JS open source community - though we're always open to suggestions.

[iMichaelOwolabi]

@iMichaelOwolabi Please see this comment above.

I don't foresee us changing how we currently create the documentation and build the site - since this is a pretty standard way of doing things in the JS open source community - though we're always open to suggestions.

Thank you @kaicataldo

[codeliezel]

I sent in my proposal with the project idea to Restructure and Rewrite the Eslint Configuration Documentation. before the deadline.

I'm excited for what will be the turn-around. 😊

I've been using Eslint ever since I decided to start a professional career in tech(2018). It will be a honour to contribute to this amazing tool!

[nzakas]

Thanks @codeliezel! We are in the process of reviewing all of the proposals we received (21) and will be making a decision soon.

[kaicataldo]

Closing this in favor of https://github.com/eslint/eslint/issues/13632. Excited to get started!