Clean up docs for react-webpack-rails-tutorial

Open
#525 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
25/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Tech stack
javascript, rails, react, webpack
Domain
documentation

Research direction

Start with the README sections for the videos, Fonts with SASS, Webpack Additional Resources, and Basic Demo Setup, then inspect docs/additional-reading/heroku-deployment.md, PROJECTS.md, KUDOS.md, and client/app/assets/fonts. Verify the referenced links and instructions, identify current replacements or platform guidance, and update the tutorial so its links work and its setup coverage is current.

Written by the indexing model from the issue text.

Description

documentation

The tutorial is a great resource that can help a lot of developers who want to use react in combination with rails. However, after thoroughly going through it, I believe there are a couple of recommendations I would like to make to help it become even better.

  • Old and outdated links: In a fast technological world where everything seems to change quickly and things get outdated within a few months if not weeks, there is the need to update and use the latest information or tutorials to give the user a smooth and nice experience without any setbacks. However, I encountered some references and links to tutorials as old as 8 years. A few of such examples are listed below:

    1. The testimonial from Joel Hooks, co-founder, chief Nerd at egghead.io is more than 6 years (January 30, 2017). I strongly believe with the improvements and iterations ShakaCode has gone through since then, there should be new latest testimonials from companies which will better tell the story. Also further reference to the projects and kudos and testimonials for using react-rails dates back to 2018 which needs an update.

    2. Under the videos section in the readme file, all the three videos hosted on youtube are more than 6 years old. You can even see Justin Gordon (the host), saying: “Yes, I plan to update this! There are a few differences” under one of the comments (and that is 5 years ago!).

    3. This article, which is more than 8 years old, was referred to as an example of how to use React with Css Modules inside of Rails.

    4. Under the title Fonts with SASS, a reference was made to this fonts, which is more than 8 years old as the font files loaded by the Rails asset pipeline and the webpacker HMR server.

    5. Another link which is close to 8 years old is the link to Pete Hunt's Webpack Howto, under the title, Webpack, Additional Resources.

  • Broken link: I also noticed a broken link, heroku-deployment.md. under the title “Rails Integration”. I believe this may be an oversight which needs fixing as soon as possible.

  • No alternative instructions given. Under the title “Basic Demo Setup”, I noticed that instructions were given on how to install and set up Redis for MacOs users using Homebrew. However, no alternative instructions were given to the users of Linux and Windows (you will be surprised how many people are using these OS).

The above listed points are just a few of the things I noticed which can be resolved to help improve the tutorial.

Dominant language
JavaScript
Stars
1.7k
Forks
370
Avg merge
2d 15h
Merged PRs (30d)
6

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from shakacode/react-webpack-rails-tutorial

All issues in shakacode/react-webpack-rails-tutorial

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.