New DUB documentation
bachmeier
no at spam.net
Fri Nov 24 14:33:40 UTC 2023
On Wednesday, 22 November 2023 at 21:35:34 UTC, WebFreak001 wrote:
> the revamped DUB documentation I started a while ago is now
> deployed on https://dub.pm
Limiting my comments to the "Getting Started" page, since that's
obviously where new programmers will go first.
On the very first page, there are links to the DUB registry
website and assorted man pages. You've just lost half the
audience right there. The best possible outcome is that the user
is confused but pushes on. It says "You can also skip ahead to
First steps if you already have dub installed." How do they know
if it's installed?
The first page has to be crystal clear. It can't have
distractions or require knowledge of the installation status of
this thing called "DUB".
The "First Steps" page is likely to be the last steps for many.
It provides a CLI command and then shows a bunch of output from
an interactive session with no explanation. That's followed by a
brief discussion of directories and files. There's also mention
of .gitignore, so I guess that means Git is required to use DUB.
Then there's discussion of two formats, with no information on
how to choose, or why it's important. That's followed by a
presentation of configuration files with no explanation.
I wish I could be positive, but this doesn't move the needle. The
two key ingredients for a getting started guide are examples and
explanations, and both are missing.
More information about the Digitalmars-d-announce
mailing list