marcglasberg / async_redux

Flutter Package: A Redux version tailored for Flutter, which is easy to learn, to use, to test, and has no boilerplate. Allows for both sync and async reducers.
Other
234 stars 40 forks source link

Minor Editing Inconsistencies in the README.md #55

Closed psygo closed 3 years ago

psygo commented 4 years ago

While reading the README.md, I've noted some inconsistencies that might make the document less readable or harder to maintain, albeit only slightly — the numbering is only for you to more easily refer to each item —:

  1. Sometimes there are hard tabs (\t) and sometimes only spaces as tabs. Which one is the norm for this repo?
    • Many editors convert tabs to spaces under the hood, which could be a solution to the tabs vs spaces dilemma.
  2. Usually it is recommended to use []() for links instead of <a> tags in Markdown.
  3. In some (un)ordered lists, the content of subsections or code-blocks does not follow the indentation of the list.
  4. Some code-blocks have not been properly indented.
  5. Sometimes - are used for unordered lists, sometimes it's *. Which one is the norm for this repo?
    • Most people recommend -.
  6. Some ordered lists are not properly numbered. This could be avoided if there were no numbering at all, only prefixing the items with 1..
  7. You opted for breaking paragraphs and phrases internally with single line breaks. I don't know what's behind this decision, but it seems unnecessary to me since editors do the line breaks in the background for readability anyway. At any rate, the main problem with this, to me, is that I can't really figure out a rule for when I or another contributor should do an internal line break.

Which of the above would you like fixed? All? None and they are all irrelevant?

I would also like to mention that it seems to be very difficult to maintain such a huge README.md. I would suggest breaking it into more concise files and creating a minimum minimorum guide for those starting out.

If you break each section into a single file, there are mini programs/extensions to put them all together sequentially inside the README.md again.