rakuguide icon indicating copy to clipboard operation
rakuguide copied to clipboard

Style/wording review

Open Altai-man opened this issue 5 years ago • 1 comments

Listing here some places we have found in English version during reviewing of Russian translation.

  • Section 1.2 title is Jargon. However, in this section we have tools names and no jargon at all. Probably needs to be renamed to something more appropriate.
  • In section 3.4 (Types), it can be nice to add output.
  • In section 7.4, list is used for only two elements. It is possible that it'd be more nice when seen in a single sentence.
  • Intro explains about keywords such as does or is, but in fact those are traits, so it is a bit of misguiding here. But I am not sure how to explain such concept in, well, introduction. Similar thing, it says keyword has(used to define attributes), but in fact it is a scope declarator, not a "keyword". Or I am wrong here.
  • Usages of "Output" inside of code tag and without it is mixed and inconsistent.

We did not review everything yet, so maybe new points will be added in comments later.

Altai-man avatar Jul 07 '18 18:07 Altai-man

Section "9.7.1. Introduction", sentence "NO! We should use inheritance" firstly, seems a bit out of place with this capitalization and lacks dot at the end too.

Section "9.9 Roles", "Classes that wish to implement a role, do so using the does keyword". It seems a bit misleading or a bit strange to me. It is not a keyword that does implementation work. It may be better with something like Classes that implement a role declare about that using does keyword or something around this area.

Section "11. Regular Expressions", "is used to check if a string (enlightenment) contains the word (light)" - maybe we want quotes here, not parenthesis?

Altai-man avatar Jul 08 '18 13:07 Altai-man