Documentation

[mattecapu]

@mjackson where's all the documentation gone?
I had to navigate through the sources to understand some odd behaviour of map(), because the Wiki is not available anymore.
I remember some days ago it existed, where is it now?

We should also expand it because mach is full of amazing features we can't reasonably expect one to discover looking at comments within internal source code...

[mjackson]

@mattecapu The wiki was way out of date so instead of leaving it up with the push towards 1.0 I decided to take it down so people wouldn't be confused. But yes, I completely agree with you that mach is full of amazing stuff that is really hard to discover right now. :/

Ideally we could just start documenting the 1.0 stuff in a docs directory in the root of the repo. This would basically be a bunch of Markdown files that explain various features of mach, similar to what @rpflorence and I are doing over at rackt/react-router.

I know that @hassox was interested in writing some documentation as well. Now that the 1.0 API has settled, I'm ready to take it on too.

I'll make a high-level outline today of stuff I'd like to include in the documentation. Hopefully that will give us a good place to start. @mattecapu If you can help at all it would be very much appreciated! :)

[mattecapu]

Hi @mjackson, thank you for your interest.

I'd love to help and do some work, but I'm not a thorough "expert" of the library yet (that's one of the reasons I'm asking for some docs 😄 )
For now maybe I can help structuring and formatting the docs, by gathering the comments I saw across the codebase? Tell me how I can be the most useful.

As to the structure, I found handy the structure of the bluebird API documentation, but probably it can be improved with a less centralized structure.
However, I think the crucial point is to make it easily accesible, for instance with links from the main README (like those already present pointing to actual code). Where they actually point is a matter of preference.

[hassox]

Yup, I'm down to write some docs. I'll try and make time this week during the evenings. @mjackson if you have ideas on what and how you would like it lemme know!

[mjackson]

the crucial point is to make it easily accesible

Totally agree on this point. Ideally I'd like to have our "table of contents" right in the README. That's what I was trying to do with the links to the source, because that's the most current source of docs we've got right now.

@hassox Sounds good. I'll definitely get an outline in this evening of stuff I'd like to cover in the docs. We can track progress here.

[mjackson]

@mattecapu @hassox Just FYI, I put the wiki back up. Let's put everything in there.

[mzedeler]

Why not put up a notice, then?