improvement suggestions for BDD Flutter blog #150
Description
Here are some points, mainly related to English language and grammar, readability and understandability, that I noticed when reviewing the PR for BDD Flutter blog updates.
- "App" is sometimes spelled with capital letter and sometimes with small letter. I think it’s more common to spell it with small letter. Please make the spelling consistent.
- For the the flutter link in line 15, the current link lands on a page where the types of testing are mentioned as a bullet but no further information is shared. I think this page would be more helpful for the reader: https://docs.flutter.dev/testing/overview
- In line 18 there is the first mention of Cucumber. Up to that point only Gherkin was mentioned. I think this could be a bit confusing to the reader. Also adding a link to Gherkin Documentation/Reference at the first instance Gherkin is mentioned (line 13) would from my point of view add some value to those readers who are not that familiar with Gherkin. You could for example link to this page: https://cucumber.io/docs/gherkin/reference/
- Since the abbreviation BDD was introduced in the first sentence (line 13), there is no need to repeat “BDD (Behavior Driven Development)” throughout the text. Just use “BDD” or “Behavior Driven Development” at later instances, but not both
- Line 28: Currently the flow of text doesn’t look nice. It would be more readable if you add a proper link like this: “But enough theory, let’s get our hands dirty. _Note: You can find all the code of this tutorial here_”
- Title on line 30: either “The feature file” (singular) or “Feature files” (no article)
- Line 76: This is no proper sentence… You could for example change it to this
“After adding, run
flutter pub get.” or add this sentence fragment to the previous sentence in line 68 - Line break in line 150 breaks the flow. I think the stand alone line 151 can be added to the paragraph above
- Adding code snippet of main.dart after line 161 might be helpful for the reader
- Some sentences are quite long. For readability it would be easier to break them into shorter sentences. Additionally, it is more common to use points or depending on context double points for this. Semicolon like in line 45 is rather uncommon.
- In English language there should be a point at the end of each full sentence (e.g. line 32). And also using commas at the right places helps with readability :)
- Plus sentences usually start with capital letters (e.g. line 177)
Originally posted by @koebel in #147 (review)