Style Guidelines discussion

[ZanaDev]

I think it might be pertinent to discuss the overall manual style in an issue.

I've made several decisions and adjustments to the manual so far based off of what seems correct to me, but I'll share my choices so that it's clearer what my intent is and so they can be discussed.

Removal of "casual conversation" words

There have been a few instances in the manual of certain words or phrases that seem somewhat out of place in a technical document, but I suppose this is very subjective. They are not explicitly incorrect. Stuff that falls into this category includes "a lot," "bigger," "things," etc.

Use simplest but most concise words available to describe a feature

Kind of at odds with the above I guess. There's only been one notable case of this so far that I've felt needed adjustment, which has been the word "analogous." I consider it very possible that someone, especially a non-native English speaker, could come across this word and not immediately know what it means. Again, this is quite subjective, and maybe I'm just not giving people enough credit.

Removal of fluff phrases and descriptors

Phrases like "indeed," "in fact," "[Item] can do this and even that," etc. don't often add anything to the information presented. There are cases where it's appropriate if the information would be extremely surprising, but these are rare.

Other fluff phrases include "some [Item(s)]," and inappropriate usage of "also" and "additionally."

Removal of purely subjective content

Luckily very rare so far!

Pure opinion isn't particularly useful; it is not up to the author of the manual to decide whether a feature is helpful or not, although explaining possible use cases is a different story. Recommendations on where to look for more information, or guidance on where to go next, however, is completely fine in my opinion.

Colons and capitalization

I'm currently using lowercase letters after an instance of a colon in standard paragraphs. These can actually be capitalized (as I've recently discovered...). I don't care which one is used.

Bulleted/Numbered Lists

I currently am adding colons before every bulleted or numbered list begins. As far as the contents, the manual has them set up in various ways. Some are composed of one sentence split apart into separate bullets, others are one full sentence per bullet, others aren't full sentences. I've made no explicit adjustments to this situation so far.

I've added periods to the end of every list item that isn't a continuous split sentence, which may or may not be appropriate.

Oxford comma

Using it where appropriate.

e.g. and i.e.

I've been replacing these with "for example" and "for instance," or slightly modifying sentences to exclude their use. I consider them unnecessary, somewhat unclear, and they occasionally ruin the "flow" of a sentence.

Metadata

I think this has been agreed upon. Currently I'm replacing instances of ":metadata" with "@:metadata."

Function type syntax

There appears to be an ongoing discussion on how the function type representation should be structured. I have not touched any instances of them in the manual currently.

I think that's most of the changes I've been focusing on. If you feel something should be added or adjusted, please share and discuss :)

[markknol]

Function type syntax
There appears to be an ongoing discussion on how the function type representation should be structured. I have not touched any instances of them in the manual currently.

I think we should follow the "standard" of what the haxe formatter does by default:

final test1:() -> Void = () -> trace(1);
function test2(fn:(x:Float, y:Float) -> Float) {
	trace(fn(1, 2));
}

https://haxe.stroep.nl/formatter/#N4Igxg9gJgpiBcIBuBDATgAgB7wBQEoBaAPgDUIBLKDAXgwIxIwBc0UwZcBGfAbgB0AdkIBmAV0FhmFCIJYwAzs1wjBeHADEANhBTMANBgCe8bbuZFiZvfmBCMLNhxWDu+gEx8hAXxD7wsiIUAOYIIMC+3kA

[Simn]

I agree we should align with haxe formatter for all code-related styling.

[Gama11]

In fact, the code snippets in the manual should probably simply be run through haxe-formatter (the std lib already uses haxe-formatter anyway).