improvement suggestions for BDD Flutter blog

[koebel]

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 https://github.com/JankariTech/blog/pull/147#pullrequestreview-2141492521

[koebel]

Additionally, the following changes related to writing style and understandability have been suggested in https://github.com/JankariTech/blog/pull/147

https://github.com/JankariTech/blog/pull/147/files#r1658213438 https://github.com/JankariTech/blog/pull/147/files#r1658218263 https://github.com/JankariTech/blog/pull/147/files#r1658217530 https://github.com/JankariTech/blog/pull/147/files#r1658220272 https://github.com/JankariTech/blog/pull/147/files#r1658224402

[grgprarup]

Creating a separate issue for the PR comments is not a good idea. It's better to add and resolve the suggestions in PR itself.

[koebel]

Creating a separate issue for the PR comments is not a good idea. It's better to add and resolve the suggestions in PR itself.

it was suggested by @individual-it to separate fixing content and improving writing style and understandability :)

[individual-it]

The original PR should be about fixing issues in the blog that make it be not-up-to-date e.g. code or outdated links. In my opinion this is a separate work, as it is about the general writing style etc.

[grgprarup]

The original PR should be about fixing issues in the blog that make it be not-up-to-date e.g. code or outdated links. In my opinion this is a separate work, as it is about the general writing style etc.

Then I don't have to address suggestions in PR https://github.com/JankariTech/blog/pull/147.

[koebel]

I guess for traceability it's better to separate, but I think you already started implementing some of these suggestions, so don't delete the work you've already done! Would it be easy to copy what you have already done into another PR?

[koebel]

while most of the points above have already been addressed in PR https://github.com/JankariTech/blog/pull/147, here are a few more things regarding clarity and readability that came up when reviewing https://github.com/JankariTech/blog/pull/147

• line 21: final level of what? (see https://github.com/JankariTech/blog/pull/147/files#r1666626426)
• adding code snippet of main.dart after line 161 might be helpful for the reader to better understand and be able to reproduce the steps described in this paragraph
• line 190 is not a proper sentence. If it's considered to be a continuation of line 177, there shouldn't be a double point at the end of line 177 and line 190 should start with ... and the app (see https://github.com/JankariTech/blog/pull/147#discussion_r1666661602)
• titles: some of the titles are written using the all capital style, others don’t even use capital for the first word of the title… it would be nicer to use the same writing style for all titles