Ts-loader: [docs]: improve for beginners?

[jsjoeio]

Per a conversation on Twitter with @johnnyreilly, the docs could use a fresh set of eyes. As someone who has never used ts-loader, I will have the beginner mindset and be able to catch anything more veteran users might not have noticed with the docs.

The Plan

• Go through docs
• Keep notes on confusion or questions
• Get clarity here (on this issue)
• Open PR with changes (if any)

How does that sound?

[johnnyreilly]

Sounds like a plan!

[jsjoeio]

Areas to improve

ts-loader repo link points to a blog post about Yarn PnP

As someone new to ts-loader, when I come to the repository and the first link I see is a blog post. I click on it. When I start reading the post, I soon realize it's about Yarn PnP rather than ts-loader.

proposed solution: remove blog post, or add a link to a blog post that explains ts-loader

description of package assumes prior knowledge

This description assumes prior knowledge:

This is the TypeScript loader for webpack.

As someone new, I may know what TypeScript and Webpack are, but I don't know what loader means in this context. Even after skimming the whole doc, I'm not 100% sure what the package is for. I assume it's for projects that use Webpack as their bundler and want to write their code in TypeScript? But still not sure.

proposed solution: update description to explain it using more beginner-friendly language

no table of contents

This README is rather dense. To make it more approachable, it would be nice to include a table of contents to be able to jump to various sections and find what I'm looking for faster.

proposed solution: add a table of contents

improve /examples READMEs

When I go into the examples, I notice there are several, which is awesome! But when I click on each example and look at the README, I'm not sure what the example project is. I think these could be improved by adding a simple paragraph at the end of each. Similar to the way next.js does it.

proposed solution: update README in /example projects

reorganize README to see INSTALLATION sooner

When I come to a repo, the first thing I want to see is what it is and how to install it. Then later I can read about "Faster Builds" or other information.

proposed solution: move INSTALLATION section more towards the top

format the words "ts-loader" consistently

The name of the package is used inconsistently throughout the README. Or rather, the formatting of it is inconsistent. Sometimes it's an inline code-block. Other times, not. I think we should decide on one and stick to it throughout the README.

proposed solution: format "ts-loader" consistently throughout README

recognize all contributors

I noticed there are 96 contributors to this project. I am certain the maintainers of this project are grateful and have already done a wonderful job thanking and recognizing them. I see the next level to that as adding the all-contributors bot to this project, which would add the contributors table to the bottom of the README. You can see an example of this in [react-testing-library](https://github.com/testing-library/react-testing-library#contributors).

proposed solution: add all-contributors bot to project

Summary

Here's a summary of changes I'd like to propose for this project:

• [x] modify repository website link
• [x] update short description under shields
• [x] add a table of contents
• [ ] update README in /example projects
• [x] move INSTALLATION section more towards the top
• [x] format "ts-loader" consistently throughout README
• [ ] add all-contributors bot to project

@johnnyreilly let me know what thoughts you have! After we discuss and agree (or disagree) to any changes, I'm happy to start on a PR. Some of this I can do myself and other bits will require assistance from someone with more contextual knowledge :)

[johnnyreilly]

I really like your plans! Particularly the "recognize all contributors" one - recognition is a great motivator.

ts-loader repo link points to a blog post about Yarn PnP

Yeah - if I've written a ts-loader blog post that I think might be interesting to ts-loader users I'll often use the link at the top for this. It could be confusing. I have removed the current link for now.

Do you want to start raising PRs to start tackling this? Take your time, there's no rush. I'd suggest batching it up into multiple PRs rather than one giant one. I'll collaborate with you along the way as you raise them.

Thanks for all your work 🥰

[jsjoeio]

Awesome! Thanks, @johnnyreilly !

Do you want to start raising PRs to start tackling this? Take your time, there's no rush. I'd suggest batching it up into multiple PRs rather than one giant one.

Yes! Great idea. Going to start today and do it as I have time 😄

[plastikfan]

Please could you include a trouble shooting section. There's not enough information about how to fix errors and as a beginner, I need this.

[plastikfan]

Actually, is there anyway I could get involved with reviewing documentation. I would like to help out in anyway I can. Perhaps if I can get involved with the documentation some way, it could help out in my own personal issues I have with trying to learn from the documentation provded.

[johnnyreilly]

Please do! If you'd like to take a look at the docs we have and try and improve them we'd be very grateful indeed!

[jsjoeio]

@plastikfan fantastic idea! Feel free to add in that section as you see fit and let us know how we can help

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale[bot]]

Closing as stale. Please reopen if you'd like to work on this further.