Reviewing https://www.codementor.io/garethdwyer/building-news-word-clouds-using-python-and-repl-it-sy7l88roq
Its informative, builds a fun project and does so within a 30min session. Kudos! The article felt a little rushed in the beginning, and I think that’s due to how much info is being taught. Perhaps assume the reader has some knowledge of the tech stacks ( I’ve suggested dropping Bootstrap, for instance )
- Now instead of displaying our article in <p> tags, we’ll put it inside and <img> tag
- > inside an <img/> tag
- and less padding to our images to stop them touching each other.
- > how does less padding, stop them touching?
- we add an <a> tag to add a link to our image
- > with an <a> tag a link is added to our image ( and followed by another and )
- at how to use RSS feeds and process and serve images directly in Python, but…
- > at how to use RSS feeds, process and serve images directly in Python. ( and + and )
- Consistency: url vs URL, Repl.it vs Repl, Jinja vs
jinja
Its hard to grok where the code should go exactly, I’m not familiar with python, and the tiny amount of cognitive load to guess, if the function should go on top, near the bottom, etc. Small amount of context, makes it feel smoother. Perhaps another touch, could be the filename as a comment near the top?
…or remove the references to line numbers entirely. The exact lines of code may not be important. I’m partial to the latter.
Not sure how full the article is, and at a point I was wondering what concludes it? Perhaps a few bullet points near the beginning will help:
- We’ll set up Repl.it
- Fetch our data
- Create a web server, and do some basic rendering
- Build word maps in memory
- Do some final polishing and tweaking
- Celebrate with a bagel!
The Article Help feels unecessary, perhaps replace with an object literal?
Each topic is explained ( not bad ), but some of it is irrelevant to the heart of the feature. I’m thinkig of Bootstrap. Import it, show the code needed to use it, but perhaps don’t explain the CSS? Perhaps on that note, put the “Passing URL” section before and leave the CSS till last? So that we don’t have to hold the reason of changing “{{artictle}}” to “{{article.url}}” mentally, before seeing why. That’s not to say the “problem” of need a link shouldn’t lead those paragraphs. “We need to link back to our news stories…”.