Converting all tutorials to markdown

[EJIqpEP]

What about converting tutorials to markdown. I will be easier to maintain and read them. Because comments in plain file is difficult to read. I can make PR if you want with converted tutorials.

[happypoulp]

You're probably right :). I went for this format in the first place to move fast and to focus more on content than presentation. But I agree that it does not provide a very good UX in the end.

I'd appreciate any PR! We should probably find a better folder structure to have one or more JS example to be linked to a given markdown file.

Thanks!

[vieks]

Hi happypulp,
I want just to thank you for this tutorial !
This is very great to begin and understand redux.
Keep going & nice job ;)

[happypoulp]

@vieks , thank you, I am glad it was of some help!

[mr-wildcard]

Thanks a lot / Merci happypoulp. Looking forward to reading the last part. 👍

[enzolamzo]

Hey @happypoulp, what about bundling it in a gitbook?
Great job btw!

[winkler1]

Going through this now. Actually really like in in my editor as code (https://twitter.com/winkler1/status/628643765050322944). Somehow the "feel" of reading code in IDE, with familiar code hilighting and careful line-by-line reading, works more better than a web page.

If there's a markdown version, I'd hope it would be generated from the JS, and the JS version is the source of truth :)

[happypoulp]

@enzolamzo actually I don't know much about gitbooks but when I'll be done writing tutorials I'll definitely try to make them a bit more user friendly... This is taking a bit more time than I though it would initially :D and summer vacations are coming so it may not happen until September.

[happypoulp]

@winkler1 I am happy that you liked it!

It would be good to have those JS as the source of truth for the MD but I have no idea how I would do that through an automated generator (since JS comments are not expressive enough to easily be translated to rich MD).

Any suggestions are welcome ;)!

[olegstepura]

@happypoulp just want to thank you for this great work. It makes understanding what happens and how to customize things much easier.

👍

[happypoulp]

@olegstepura , you're welcome ;).

[Jakobud]

One thing I was confused on with the tutorials so far is I was wondering how the JS files work together. It took me a bit to understand that each .js file was just an independent file by itself and is not mean't to work with the other JS files. I think that splitting the tutorial up into Markdown via the Wiki or something would make this a lot more clear.

[Jakobud]

I've started this process. Anyone feel free to jump in and help

https://github.com/happypoulp/redux-tutorial/wiki

[happypoulp]

@Jakobud thanks for the wiki!

[ivanoats]

What about using Docco to process the comments in Markdown? This process worked in the past for backbone and underscore... https://github.com/jashkenas/docco

[happypoulp]

Thanks @ivanoats, I'll have a look, this may be a good solution indeed!

[Jakobud]

I wouldn't over-complicate things. Honestly it took me about 2 or 3 minutes per tutorial to convert it. Not a big process.

[patrick-jones]

I'm with @winkler1 -- I like looking at the code with the explanation in my text editor. It was very easy to run and read through (with syntax highlighting!) all of the examples right in Atom. I found it much more convenient that hopping back and forth between code and browser.

By the way, if I knew how to buy you a beer or a bottle of wine I would. This is an exceptionally clear, helpful, and to-the-point tutorial.

[happypoulp]

Thanks @patrick-jones :D, I appreciate the intention!

[TehShrike]

Would you accept pull requests that did this manually, one file at a time, or would you only merge a pull request that converted all the files at once?

[happypoulp]

@TehShrike, thanks for the proposition but it has already been done in the wiki section: https://github.com/happypoulp/redux-tutorial/wiki

So for those that the current JS format does not convince, they can use the wiki instead. But it seems that there are also many people that find the current JS format useful so I am thinking of living it that way for the moment.

Thanks anyway!

[TehShrike]

Ah, it's cool that it's in Markdown form, but it's a shame it's outside the repo - I like to make pull requests for typos or grammar issues while reading markdown-books-on-Github.