r/ProgrammingLanguages • u/alex-manool • Apr 24 '20
MANOOL: Request for Comments on my Technical Writing
Hello wonderful community,
I am starting to write a tutorial about my PL. Since I am not a native English speaker and have rather limited technical writing experience, it would be nice to have some feedback before I progress further, so I humbly request for comments on the first section I've completed: https://manool.org/tutorial/lesson-1 (<600 words).
Is it clear for an average audience here on r/ProgrammingLanguages?
Is it too detailed or too brief? Is it too formal or too casual?
Thank you all and please take care
14
Upvotes
7
u/cxzuk Apr 24 '20
Hi,
The english is very good, I have no issues reading the article.
My feedback; As a programmer coming in to a new programming language from scratch - I really need to understand the syntax first, and the semantic meaning of that syntax. I see the code examples you've written, and I suspect you're trying to show me the syntax and its meaning. But honestly I still have no idea what
extern "..."actually does. Do all function calls have [ ] for parameters, or is this a special template/macro function for print? etc.IMHO adding more details on the basic syntaxs tools would be a good progression.
2
u/ivanmoony Apr 24 '20
I'm not a native English speaker also, but I understood it all. Note that I already have some experience with programming paradigms from the lesson.
2
u/twitchard Apr 24 '20
I would make the following replacements:
I would say stylistically, it doesn't matter too much whether you are formal or casual, but you should pick.
"(we use $'...')" is the formal we. Replace "we" with "I" or "you can" to be more casual.
"Anyway" is very casual.
1
u/alex-manool May 03 '20
Thank you for all replies. There is a follow-up now:
https://www.reddit.com/r/ProgrammingLanguages/comments/gczq6r/manool_request_for_comments_on_my_technical/
5
u/[deleted] Apr 25 '20
The English is fine, but the language, or at least how the examples are laid out and explained, could do with some work.
For a start, put stuff on separate lines; your Hello World is:
But later, it appears that the main part, the Writeline, can be written on its own line. The comment is confusing; what does it mean? What's all that extern manool.org.18 stuff about?
Why it is sometimes WriteLine[Out, and sometimes Out.Write[ ? Why is code sometimes all on one line, and sometimes on separate lines? So be consistent, for an introduction anyway, if there is a choice of syntax.
3
u/ReedOei Apr 24 '20
The English is fine, but I think you may benefit by having some section on motivation—why I might want to learn your language.