[doc] TOOLS-594 eng update README.md.

- `rm server.js`: stale worse than nothing.
- Sub-headings markdown.
- Added sections based on what's used in real Joyent repos.
> At least a prose statement to make it clear the context.
ok

>  eng.git is valid for more than SmartOS
I had a casual conversation about "valid" some weeks ago with some of the developers in the SF office and the consensus was that although "make docs" would be appropriate for mac, we are not currently interested in supporting REST API services on anything other than SmartOS.