Re-write the README.md

[marcelstoer]

#769 is the first attempt at getting the README.md right. I'd like to use this issue to discuss what direction we should be taking once that PR is merged.

We (i.e. the current collaborators) already agreed that:

• The code samples need to be removed. Examples belong in the examples folder and at best the README should contain a link or reference to these.
• It should be shorter i.e. more concise.
• It should contain a summary of the project status referring to Policy for maintaining open issues #719 for our policy on accepting new issues.

[jmattsson]

• Link to the FAQ
• Link to recommended forums for getting user help (closely related to Policy for maintaining open issues #719)

[nickandrew]

I suggest a .md file for each module, fully documenting what the module does. Example code snippets can help here.

Code samples in README.md can also assist somebody who's thinking whether they should use NodeMCU, by showing how easy it is to program.

[marcelstoer]

@nickandrew API documentation is handled in #774, I just created it.

[ghusson2]

Maybe there should be some advises about how to use nodemcu in general. I mean for example, adding a timer before running scripts at startup (in order to have the time to upload a code update in case of big bug), how to cut long instructions sets in different scripts and so on.
Maybe some advises from http://www.esp8266.com/wiki/doku.php?id=nodemcu-unofficial-faq.
And maybe and most important some "begin from zero here" (i did it for my fablab in french : http://fil.crepp.org/pages/view/51/nodemcu). On this last, I can translate it if you want (but linux oriented).

[marcelstoer]

Maybe some advises from http://www.esp8266.com/wiki/doku.php?id=nodemcu-unofficial-faq.

My plan is to integrate the FAQ into the wiki replacement with #774 (and move it from unofficial to official finally 😉 ).

On this last, I can translate it if you want

Once the documentation is based on RTD serving the docs in multiple languages should be a breeze.

[ghusson2]

Ok, just perfect 👍

[nickandrew]

@ghusson2 I'll compare your "begin from zero" document with the latest README; there might be places I can add detail. No need to translate from French; it's obvious what most of the document means :-)

One last thing, please delete your reference to nodemcu_float_0.9.6 as that version is deprecated. Current README.md covers: cloud build (as your doc does), building in a Docker container, and installing the build toolchain directly.

[ghusson2]

@nickandrew : "latest README" : oh yes, indeed :)
Thank you I updated my doc.
Hmmm... thus there is no more prebuilt nodemcu... I guess it is because it is difficult to choose which lib to include or not and because the available space in memory io too short if everything is enabled ? So maybe you could distribute a demo firmware, in order that interested people can test quickly nodemcu (corresponding selected codes examples like blinking the LED) but with a big warning like "demo firmware, please use custom build for daily use" ? Because new potential users won't understand the need to compile the firmware (as others don't need it and furthermore it is an extra effort).
(I think I will reread the whole nodemcu git this WE, because things moved consistently and I didn't followed :))

[marcelstoer]

Hmmm... thus there is no more prebuilt nodemcu...

Please look at the current issues list. This one is #788.