{"action":"created","issue":{"url":"https://api.github.com/repos/HaxeFoundation/HaxeManual/issues/213","labels_url":"https://api.github.com/repos/HaxeFoundation/HaxeManual/issues/213/labels{/name}","comments_url":"https://api.github.com/repos/HaxeFoundation/HaxeManual/issues/213/comments","events_url":"https://api.github.com/repos/HaxeFoundation/HaxeManual/issues/213/events","html_url":"https://github.com/HaxeFoundation/HaxeManual/issues/213","id":111264979,"number":213,"title":"Style Guide","user":{"login":"indolering","id":44454,"avatar_url":"https://avatars.githubusercontent.com/u/44454?v=3","gravatar_id":"","url":"https://api.github.com/users/indolering","html_url":"https://github.com/indolering","followers_url":"https://api.github.com/users/indolering/followers","following_url":"https://api.github.com/users/indolering/following{/other_user}","gists_url":"https://api.github.com/users/indolering/gists{/gist_id}","starred_url":"https://api.github.com/users/indolering/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/indolering/subscriptions","organizations_url":"https://api.github.com/users/indolering/orgs","repos_url":"https://api.github.com/users/indolering/repos","events_url":"https://api.github.com/users/indolering/events{/privacy}","received_events_url":"https://api.github.com/users/indolering/received_events","type":"User","site_admin":false},"labels":[],"state":"closed","locked":false,"assignee":null,"milestone":null,"comments":6,"created_at":"2015-10-13T20:34:01Z","updated_at":"2015-10-15T08:05:21Z","closed_at":"2015-10-14T19:41:49Z","body":"I have a background in technical documentation and I think the Haxe manual would benefit from guidelines both on the tone and composition.  Sadly, I'm slammed with research and work at the moment but I'm hoping to at least spark a discussion.  So here is a shorter version of the ticket I don't have time to write : P\r\n\r\n### Tone: informal, if not first person.\r\n\r\nThe manual often sounds like a paper on the language design of Haxe.  The following example was written as a logical proposition with antecedent that implies a consequent:\r\n\r\n> The variable `child` is explicitly typed as `Base` to highlight an important difference: At compile-time the type is known to be `Base`, but the runtime still finds the correct method `myMethod` on class `Child`. It is then obvious that the field access is resolved dynamically at runtime.\r\n\r\nThis is oft-putting to readers and the claim that it is \"obvious\" is demeaning to anyone who didn't find it obvious.  We should try and excise this academic tone.  If the manual is designed to be a book, then I would strongly suggest a first person dialogue with the reader.\r\n\r\n### Structure: explain what you are going to explain, then explain it.\r\n\r\nIntroductions should be aimed at giving novice readers some background and then switch to the task at hand.  The following introduction sounds nice, but it was clearly written by someone who muses about language design:\r\n\r\n>Overriding fields is instrumental for creating class hierarchies. Many design patterns utilize it, but here we will explore only the basic functionality. In order to use overrides in a class, it is required that this class has a parent class. Let us consider the following example:\r\n\r\nThis \"dumbed down\" version manages to get more information across: \r\n\r\n>  In object-oriented programming (wikipedia link) child classes inherent fields and methods (link to inheritance section) from parent classes.  In Haxe, child classes can customize fields and methods of a parent class using the `override` keyword:\r\n\r\n### Examples: action oriented and atomic\r\n\r\nEach section should be oriented around accomplishing a task.  [A manual is not a novel and users do not read each section](http://users.edte.utwente.nl/meij/minimalism.htm).  They spend ~5 minutes searching for material that matches the task they are trying to accomplish and emulating what they find.\r\n\r\nThis isn't Stack Overflow and each subsection section should build on previous subsections, however, they should be fairly atomic.  For example, the passage on overriding methods uses a single example to explain the basic syntax as well as run-time type resolution.  I would suggest a single page with 2 different sections (I would also move the \"Effects of variance and access modifiers\" onto the main page but meh).\r\n\r\nAnyway, I'm off to get some paid work done. I hope this is helpful : )"},"comment":{"url":"https://api.github.com/repos/HaxeFoundation/HaxeManual/issues/comments/148312344","html_url":"https://github.com/HaxeFoundation/HaxeManual/issues/213#issuecomment-148312344","issue_url":"https://api.github.com/repos/HaxeFoundation/HaxeManual/issues/213","id":148312344,"user":{"login":"markknol","id":576184,"avatar_url":"https://avatars.githubusercontent.com/u/576184?v=3","gravatar_id":"","url":"https://api.github.com/users/markknol","html_url":"https://github.com/markknol","followers_url":"https://api.github.com/users/markknol/followers","following_url":"https://api.github.com/users/markknol/following{/other_user}","gists_url":"https://api.github.com/users/markknol/gists{/gist_id}","starred_url":"https://api.github.com/users/markknol/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/markknol/subscriptions","organizations_url":"https://api.github.com/users/markknol/orgs","repos_url":"https://api.github.com/users/markknol/repos","events_url":"https://api.github.com/users/markknol/events{/privacy}","received_events_url":"https://api.github.com/users/markknol/received_events","type":"User","site_admin":false},"created_at":"2015-10-15T08:05:21Z","updated_at":"2015-10-15T08:05:21Z","body":"@jonasmalacofilho even though this topic is closed, I'd like to say that I would really like to have you on the documentation team since you mentioned you have a background in writing technical docs. :smile:  I want to invite you to help (re)writing parts that are missing or could be improved. "}}