Style Guide

[indolering]

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

Tone: informal, if not first person.

The 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:

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.

This 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.

Structure: explain what you are going to explain, then explain it.

Introductions 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:

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:

This "dumbed down" version manages to get more information across:

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:

Examples: action oriented and atomic

Each section should be oriented around accomplishing a task. A manual is not a novel and users do not read each section. They spend ~5 minutes searching for material that matches the task they are trying to accomplish and emulating what they find.

This 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).

Anyway, I'm off to get some paid work done. I hope this is helpful : )

[Simn]

I appreciate that you sit down and think about this, but I'm not quite sure what we'd actually get out of it in practice. Criticizing style is fair enough and your mentioned points certainly have some merit, yet I don't see what to do with it. We cannot write a style guide if the manual in its current form doesn't adhere to that very style. On the other hand nobody is going to rewrite the entire thing to conform to such a style either.

At best we could position it as guide for new content, but then we'll end up having style inconsistencies which I consider to be the worse option. So again, I'm not quite sure what to do with this.

[indolering]

Please try to not take offense! The skills that make for a good programmer do not transfer to writing documentation.

I appreciate that you sit down and think about this, but I'm not quite sure what we'd actually get out of it in practice.

Your "style" adds significant cognitive overhead:

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.

The child variable is explicitly typed as Base but the method calls are resolved at runtime, ensuring that the correct method from Child is called.

It also just wastes time:

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:

That paragraph contains ZERO useful information.

We cannot write a style guide if the manual in its current form doesn't adhere to that very style.

Wha? The point of a style guide is to get people thinking about how they are writing.

At best we could position it as guide for new content, but then we'll end up having style inconsistencies which I consider to be the worse option.

So you are against future contributions becoming better?

[Simn]

Cherry-picking parts which you consider to be not optimal is not gonna help much unless you go ahead and send pull requests to rewrite them. Unfortunately my style is the best we have at the moment and I doubt anyone is interested in rewriting the entire document.

I'm not against having a list of "best practices" for documentation. It's just that this is a bit too meta for me, so you would have to propose something more complete and specific.

[jonasmalacofilho]

I would add that an important responsibility of "list of best parctices" is to deal with how to gradually change from old to new style.

[ncannasse]

I agree with Simon here. That's a lot of work to change the whole manual.

If you want to contribute clarifying the manual, please start with some parts that seems the most difficult to read and submit a PR, it will be discussed and merged, then you can start doing the same for other pages.

I'm closing the issue for now.

[markknol]

@indolering 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.

[jonasmalacofilho]

@markknol , I think you meant to invite @indolering, since he's the one that stated "I have a background in technical documentation"

You already fixed it... :smile:

[markknol]

Sorry I tagged the wrong person :disappointed: But yes, I meant @indolering