Thoughts

[markknol]

Hi,

I'm opening an issue to open the discussion. First of all, really great you guys want to be involved in the docs, I really like this initiative! We need lots of hands to get docs to a next level (even though people will always will ask for more 😉), lets do it together. I think our goal is to cover as much topics as possible.

For me code.haxe is a handbook (how to use it), where the manual is the technical description of how Haxe works. While there should be a close connection (cross links) we should keep this separate, so let's keep that in mind. I know writing for the manual is harder because it has to be precise but we can use help on covering some topics you are suggesting too.

I have some questions/thoughts;

• About the target details, this is indeed something that is still lacking documentation so its a good plan to have examples to it. Beside this, I think beside this the manual should also cover some details (whats needed per target, how to build, dependencies, compiler flags and metadata explained), I started something here (but personally lacking information/experience) so any help/contributions here is appreciated.

• About debugging, I also started something for the manual too: Debugging HaxeFoundation/HaxeManual#261, while it can be in the cookbook ("how to debug x in editor y") I think it should be also covered in the manual.

• Do you think library users want to write in our docs instead of their own. For example, openFL has its own learning section http://www.openfl.org/learn/ also, HaxeFlixel also has its own documentation, etc. http://haxeflixel.com/documentation/. What do we want to cover in our "libs" section?

• I like the updated homepage! This is something that is good to accomplish once we have the stucture defined.

• I do like what Matthijs did for some of the targets: http://matthijskamstra.github.io/haxenode/ http://matthijskamstra.github.io/haxephp/ http://matthijskamstra.github.io/haxejs/ https://matthijskamstra.github.io/haxepython/ If he agrees we can copy some stuff to the cookbook, but we have to clean some stuff up too to make it suitable for the format of the cookbook.

• I had some ideas here too: Wanted articles HaxeFoundation/code-cookbook#49

• How to continue from this point?

Again, thanks and lets share our ideas!

[cambiata]

Hi Mark!

Quick response here:

Agree!

Regarding debugging, maybe Dan or Gama could write some lines about debugging with JS/Chrome and Flash in VSCode. Soon (hopefully) also C++ and HL.

Regarding the libraries, we must rely on develpers docs/github readmes in the first place. But one page with curated overview over libraries valueable for beginners (to know about and use) maybe is doable.
If library creators would like to write in code.haxe, that's perfeclty fine, of course!

Matthijs examples are great. Could his publishing sturture (gitbook?) be used inside code.haxe, or should we rely on the document structure that's already there?
Yes, his stuff is great, and if it's ok for him it would be great to find it in a more official context.
Also, Sven's articles are super informative and far to hard to find.
Hopefully, if we attribute the originators well, we could use his articles - and other writer's - inside code.haxe.

[MatthijsKamstra]

#TL;DR

I am in! show me the way!

#5ct

I agree with that the manual is a technical description of Haxe. My biggest problem is that its not written for guys like me... (no computer science degree / self thought ).

If I would ignore al the good stuff from Haxe and only use the basics there was no way to connect that to the targets. (the main reason I wanted to document that)

I would be great that my effort gets more exposure... so thx for inviting me to your "house".

Currently I see the documentation for Haxe like this:

Beginner: No knowledge at all of the topic

I don't think it possible to start with Haxe without any knowledge of programming. No docs for beginners

Basic: A very basic knowledge of the topic but no professional usage

I think my documentation helps with the targets but not with basic Haxe. I think the manual is not helping. I guess there is no easy way to start with Haxe (I might write this in the future)

Intermediate: A basic knowledge of the topic but no regular professional usage

Cookbook

Advanced: A good knowledge of the topic and a regular professional usage

Cookbook / Manual

Expert: A perfect knowledge of the topic and a daily professional usage

Manual

(And that is off course very black and white; I know there is a beginner section in Cookbook)

#docs

I think its a good idea to use what I did.. but forget python ..

The tutorial JS / NODE / PHP cover real-life problems I had.

As soon I have a use for Python I will document that as well

And the documentation I wrote is not in the style of codebook, we should adjust it for that.
I am doing a lot js currently and was updating the js documentation again

If you create a "js" folder I can work in I will start the conversion (and we can start discussing it)

[nanjizal]

I think it might be nice to have a section 'how to do' for common toolkits, it can be a bit annoying to enter each ecosystem and work out the best approach, each one seems to have a different approach and often the information is great but a hassle to find the goto place.

Stuff that should perhaps be covered.

Setup

1. Getting Toolkit setup
2. Setting up targeted code IDE

Control and Input

1. Mouse
2. Keyboard
3. Text input

Events and Movement

1. Events/Signals
2. Timers
3. Tweens
4. Physics

2D graphics

1. Draw shapes ( svg / drawing api )
2. Draw Image and SpriteSheets
3. Text
4. Masks and filters
5. Particles
6. Components
7. Swf, Flump etc... support.
8. Asset Management

Sound and Video

1. Sound starting, volume control
2. Sound3D
3. Video
4. Video subtitles

3D graphics

1. Setup / engines
2. Primatives eg: Cube
3. loading simple models obj, collada ... etc...
4. mouse keyboard interaction and world translations, quaternions
5. Skybox
6. Lights, Materials, Textures, Cameras
7. Custom Shaders

If we firmed up a list of required sections I am sure I could go through and fill out demos of each feature for many of the cross targets with help. Kha, Luxe, Flambe, Swing, c#?, NME ( OpenFL ), SVG, Canvas. But while I can give that a go really would need feedback from others, as I may well miss best practices. I would probably skip over Unreal and Unity someone else might want to cover them.

But I would love a single place that has a starting point for documenting graphics approaches. Perhaps it might make most sense to look at each target and make a list of stuff someone might want to do and how. Even if the sections just pointed to various pages of community content.

The biggest problem is most Toolkit developers don't really care about the overall Haxe graphics ecosystem in the same way that I do, they believe everyone always should use their toolkit, but what I like about Haxe is being a bird that can fly between approaches depending on my needs and interests. It's important to try to build cross referencing information so that users can really see what is possible and what might suit their project.

But I am well aware of the amount of work, so far I did not get far!
https://github.com/nanjizal/code-cookbook/tree/master/assets/content/cookbook/Graphics

having all the section mapped out might make it easier to tackle them and stay consistant, it's very easy to go too far on each tutorial. I suppose the hard part is breaking down what is the correct approaches and then sectioning them in relation to the toolkits.

It would be nice if we made sure that enough libraries were installed to demo lots of them in try haxe.

[mikicho]

Just saw this, have to insert somewhere: https://github.com/r3d9u11/haxe-basics

[cambiata]

Thank you, guys!

@markknol, some questions for you:

1. What would be the best solution for "multi-subchapter" documents, do you think? Should we stick with the "multi subchapter" document that we have now (for example http://code.haxe.org/category/other/working-with-cppia/index.html), or could/should we go for gitbook à la Matthijs's docs, or something else?

2. Would it be possible to set up a dev-code.haxe.org where we could try to find a good content structure and design?

[cambiata]

@mikicho Yes, r3d9u11's stuff is awesome! Well structured and focused. Great stuff for code.haxe!

[cambiata]

@nanjizal, Yes, an outsiders view of getting-started-with-library-x is important. At the same time, we must keep the information redundancy as low as possible, either by

1. Linking to the libraries tutorials, or

2. Getting lib authors to write and maintain tutorials inside code.haxe

BTW, this is also an nice one: https://github.com/nanjizal/CookingHaxe :-)

[markknol]

@cambiata about your questions:

1. I think it is doable to do "multi-subchapters", but maybe it can be a visual trick on the homepage,where the content stays in categories as it is right now.
2. I think ill put it in a new branch. I think the ones who are interested can also run/test a local copy.

This haxe-basics repository is great content. To make it usable, it need to convert these to articles, instead of code-only. The good thing is that is is mostly just-Haxe, but I think in essence it fits.

I'm still not sure if/how we should host the library documentation. Isn't documenting libraries a task for library owners? Should that be on code.haxe? I doubt this. I think writing docs for anything you can do with Haxe is quite ambiguous (at least all the things nanjizal is proposing), so we have to make a clear distinction. What do you think? I'm open for ideas, but I asked around and don't think "famous" libraries are interested in hosting their tutorials/handbooks on code.haxe. So having many links integrated is maybe a good idea.

Also if turns out library users don't have a place to write their handbooks/tutorials, We might consider converting the sources to allow everybody starting its own cookbook (something like dox, but for cookbooks). But that is a different project. 😉

Update: I started with some JavaScript and Node.js articles, which ill publish soon. We don't have to wait with writing for the redesign.

[mikicho]

I think that the libs docs should stay out, but in the haxe cookbook should be an entry for each library that explain a short what it does and reference to it's own docs.

[MatthijsKamstra]

I think documentation / code examples / etc needs to be done by the individual repo owner.
The documentation makes the libs popular (see the difference between heaps and openfl).
And libs popup all the time and fade away just as fast.
Cookbook should be about Haxe and the targets: it should help you with working examples.

But it doesn't mean you should stop your effort @nanjizal : I have been one of the more frequent user of my own documentation 😄

@mikicho indeed an impressive list, and its a great start to write tutorials from.

@markknol if you need help (https://github.com/HaxeFoundation/code-cookbook/blob/master/assets/content/cookbook/JavaScript/creating-node-server.md) let me know.

And I agree that node.js should have a different folder then js (although node.js is technically not a haxe target)