cesanta / mongoose

Embedded Web Server

Home Page:https://mongoose.ws

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Device Dashboard tutorial - nitpick changes

cpq opened this issue · comments

Please make several changes to the tutorial, and keep those in mind for the future write-ups:

Don't use bullet points if items are long
Only use bullet points when the list is short. Here - the bullet point list looks nice and adequate. Here, it looks good too.
Here it looks bad. Reason: when items a long, with screenshots, a reader just looses the context. Plus, bullet point list makes weird unexpected left margins. Instead of bullet point list, use no-bullet list or "steps" like here: https://mongoose.ws/documentation/#2-minute-integration-guide

Try to keep screenshots wide, and as small-height as possible
Pics look the best in the docs when they are 3:1 or something like that. Pics that are closer to square shape, look worse. If their height is more than their width, that's the worst.
Look at the login screenshot at https://mongoose.ws/documentation/tutorials/device-dashboard/#build-and-try.

  • A lot of vertical space is wasted, it is much better to trim the screenshot on height
  • Browser's frame is removed, which is IMO a bad idea

Compare it to this one:
image

IMO this is much more visually appealing. Mac's built-in screenshot tool makes a nice shadow, I am pretty sure Linux tools can do that too.

Similarly - dashboard page screenshot: half of the image is useless, and eats precious vertical real estate.

Please rework, and use those as guidelines.