Complex documentation.

[kmihaylov]

I'm setting up Sming on a new system and I noticed some complexities in the instructions.

I think we should have a pretty straightforward, one shot, do it in 3,2,1 instructions on the front page.

Currently a new user would read the github page and scroll down. There are Contents, summary, compatibility, releases (development) and Getting started.

Now Getting started should lead the user, however in the Development System Installation there are 3 choices -> Esp8266, Esp32 and Linux/Windows

I would click on Linux/Windows, but this is not the proper page for setting up the environment. The proper pae is Esp8266->Linux

I think a flatter structure would be more desirable.

For example the https://sming.readthedocs.io/en/latest/arch/esp8266/getting-started/index.html subpage might be moved one level up.

The Getting started -> Development system instalation page would be easier to navigate if it directly shows content like:

Setup Esp8266 Linux buld environment
Setup Esp8266 MaxOS build environment
Setup Esp8266 Windows build environment.
Setup Esp32 Linux build environment
.
.
.
Setup Linux host emulator
Setup Windows host emulator

I believe it would be very helpful if on the front page (on github and on readthedocs) there are some quick steps like: Start in 2 minutes:

sudo apt-get install make unrar autoconf automake libtool libtool-bin gcc g++ gperf \
   flex bison texinfo gawk ncurses-dev libexpat1-dev python sed python-serial \
   python-dev srecord bc git help2man unzip bzip2

cd /opt
git clone https://github.com/SmingHub/Sming.git
wget https://github.com/earlephilhower/esp-quick-toolchain/releases/download/3.0.0-gnu5/x86_64-linux-gnu.xtensa-lx106-elf-a5c9861.1575819473.tar.gz
tar xvf x86_64-linux-gnu.xtensa-lx106-elf-a5c9861.1575819473.tar.gz esp-open-sdk
export SMING_HOME=/opt/Sming/Sming
export ESP_HOME=/opt/esp-open-sdk
cd /opt/Sming/samples/Basic_Blink
make flash

[slaff]

@kmihaylov There were multiple changes to the documentation. Can you test if it is getting better and if not to recommend improvement(s)?

[kmihaylov]

Excuse my disappearance. Now it looks much better. I see this is thanks to the new installation script. To be honest all Sming's activity for the past few months is mystery to me.

Although one can dive reading the install script, wouldn't it be helpful if "geeks information" or "under the hood" exist in the related documentation chapter, describing the defaults? I'm talking about the versions listed here: https://github.com/SmingHub/SmingTools/releases/tag/1.0

Also I note that the SimngTools version is hardcoded.

I don't remember whether esptool2 was part of esp-quick-toolchain or Sming fetches it separately.

[mikee47]

Although one can dive reading the install script, wouldn't it be helpful if "geeks information" or "under the hood" exist in the related documentation chapter, describing the defaults? I'm talking about the versions listed here: https://github.com/SmingHub/SmingTools/releases/tag/1.0

In this instance I feel it's preferable to document the install script itself rather than risk the documentation getting stale. Less effort! Please feel free to suggest additions/changes!

Also I note that the SmingTools version is hardcoded.

I'm treating SmingTools more like dropbox so the version doesn't matter; it's just somewhere we can keep copies of all the important tools that is under our control, so stuff doesn't go missing. You'll see there are multiple versions of some tools; the one actually used depends on the install script - because the script is part of the Sming repo. it's version controlled in that way.

I don't remember whether esptool2 was part of esp-quick-toolchain or Sming fetches it separately.

The latter; it's pulled in and built as part of the rboot component.