I’m presently working on several projects that use Haxe and various frameworks in the ecosystem, and so am gradually getting a tour of the ecosystem, and occasionally I come across places where HaxeManual or API documentation omit certain nuances or variations of syntax.
I’ve read some older posts here from 2019 pertaining to contributing and read contributing guidelines in the README.md for for HaxeManual and the Haxe Cookbook, but I have a few questions regarding not how to contribute, but the substance of contributions.
Is contributing to HaxeManual open to anyone, or relegated to core contributors? Everything I’ve seen so far suggests the former.
Are atomic or aggregate contributions preferred? If one identifies several potential contributions regarding several distinct syntax / language features, should they be separated into their own pull requests, or included together?
3) Are there any areas where documentation is desired by the community or where there is just a strong need for documentation (whether new, updating existing, or tidying up), whether in HaxeManual, the Haxe Cookbook, codebase docgen comments, or any of the frameworks and libraries in the wider ecosystem?
That last question is the one I’m most concerned with. I personally enjoy writing documentation, and so would appreciate being able to identify any areas where they are needed and welcome.
Both the HaxeManual and the HaxeCookbook repos have fairly low commit counts for the previous few years, so wanted to ask before proceeding, though I recognize that is of course very likely due to the maturity of the language and existing completion of already needed / desired documentation, as well as the comparatively smaller community when it comes to languages.
As someone who’s submitted to the Haxe Manual, I just went for it, and they took it. I contributed three separate PRs because the issues I found were unrelated, but if I found a bunch of similar issues, I’d try to bundle them into one.
I can’t say where documentation is needed most, since I’m a power user focused on a small corner of the ecosystem. Within this corner, I think Away3D needs documentation the most, and it’s something I hope to do myself someday. I’d also accept critique on Echoes’ documentation, though that has like 5-10 active users.
I bet you’d have the biggest impact working on the Manual, Cookbook, and/or beginner guides. But it’s been so long since I was a beginner, I can’t tell you what needs it most.
Thanks for the insight, @player_03 ! I actually wound up finding the concept I originally thought should be added elsewhere in the documentation already. Coincidentally, I was hoping to utilize Away3D soon in exploration of writing extremely simple 3d games and scenes for maximum portability, so I’m hoping to coalesce what I learn into something useful when that time comes.
Regarding Echoes, the documentation I see in the README and inlined doc comments look quite well-written, but I’ll try building the documentation with dox soon and see how easy/hard it is for me to get a grasp on the subject matter. I’ve been meaning to learn how ECS’s work, especially since I keep seeing them mentioned in the Godot docs / community which I’ve been pouring over recently, so this gives me a good reason to do so.
HaxeManual is available; just submit the PR, and you’ll be OK. It’s not limited to the core.
keep PRs atomic. Bundle it if it’s entirely about a single Haxe feature, such as abstractions or pattern matching. Split it up if it’s unrelated. makes reviewing much simpler.
Where do you need documents? cross-target peculiarities (js vs. cpp vs. hl), macros, and abstractions. In Haxe, it is still where people get tripped up.
To be honest, simply start making changes if you love producing documents. The ecology is steady rather than dormant. In Haxe, excellent documentation is always valued.
