[Boost-build] Son of b2 - suggestions

Subject: [Boost-build] Son of b2 - suggestions
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2016-10-29 07:57:46

A few suggestions as you are getting closer to prototyping.

1  Assume nothing - absolutely nothing.  Do not assume that users are familiar with command lines, most will not be.  Command line
stuff is regarded as last-millenium. Do not assume that what is obvious to you is obvious to all.  Assumption is the mother of all
foul-ups!  Learn from the failures of b2 (see endless cries for help on StackOverflow and Boost if you doubt this harsh view).
Update documentation from each help request.  Ask why the user is confused and how he should have found the answer himself.

2  Be very reluctant to require more tools, like Python.  Every extra tool that you add will reduce the number of people who will
use it.  Half of your prospective users have never heard of Python, and barely know of Unix.  

3  Be consistent in syntax, keeping it as simple as possible. Prefer syntax strongly typed, not too permissive. Try to avoid/remove
the downright daft, like layout as a keyword.

4  Minimise the concepts.  The difference between options, commands, abbreviations and rules can be confusing. .  For example, stage
and install cause endless confusion to users.

5 Be consistent in naming. All the words include a - or a _, or none.  (Not libdir and build-dir) Is it case sensitive?

6  Be explicit about everything.  If there are variant names for difference OS, use both.  For example, say shared/dynamic, even if
you have explained.

7  Give several examples of everything.  Provide working examples using code snippets.

8  Too many tools are being too clever trying to make things 'just work' -  except that they often 'just don't' :-(

9 Ensure that when things go wrong, you don't get a "Something went wrong :-(" -  message. Say what went wrong: which file not
found, which command is wrong, suggest a better command.  Give examples of what users commonly do wrong and how to do it right.

10  Echo the effective, expanded, perhaps parsed, input.  For example, echo the command that was used.
"Command was "\b2 bootstrap", or the name and location of a batch or shell file.  Optionally query the users for confirmation that
this is what he wants, rather than what he said.

11  When a log file is produced (even if for internal use only), show a link or location of this:
"A log file is at " I:\modular-boost\bootstrap.log".

12  Avoid silently ignoring input that it not understood, either because it is wrong syntax, or not applicable, or just plain wrong.
Produce at least a warning, but usually an error message, and perhaps a suggestion.

13  Avoid later commands over-ruling previous commands.  It more often leads to trouble and confusion.
Make the user get it right!  (Before he waits two hours for a Boost build to run, but finds that every compile has failed :-(  )

14 When there are variants for Windows and *nix, assume Windows, and assume Windows users are less smart.

15  Say 'why', or allow users to optionally ask 'why?'.  

Good luck!

Paul

PS I admire your courage - unseating CMake will be hard now.  Son of b2  needs to be more user-friendly as well as better.  A better
(google-friendly) name than b3 would be good too, but I've no good ideas.

---
Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
[phone]