On Mon, Jan 30, 2023 at 08:39:33PM +0000, bachmeier via Digitalmars-d-announce
wrote:
> On Monday, 30 January 2023 at 04:40:48 UTC, Siarhei Siamashka wrote:
> > On Monday, 30 January 2023 at 02:44:50 UTC, bachmeier wrote:
> > > if you put your code in directories that match the modules you
> > > want to import, there's no need for Dub and the corresponding
> > > poorly documented configuration.
> >
> > What is poorly documented? Can you suggest some documentation
> > improvements?
>
> That ship has sailed. I've given up on Dub because those who promote
> it aren't interested in criticism. I'll just link to [this
> page](https://dub.pm/package-format-json) and if anyone thinks that's
> acceptable documentation for someone new to the language, there's no
> point having a conversation about it.
+1. What we need is a dub tutorial that leads you step-by-step how to
set up a project, what to put in the config file, explain what each
config item means (at least for the basic cases), and a FAQ explaining
commonly encountered issues and how to resolve them (or why a particular
use case is not possible).
Yes, all of this information is already there on the linked page. But a
newcomer (1) does not know 80% of what the items there even mean, (2)
does not understand how dub uses this information and what effects they
have, and (3) does not know which 5 of the 100 or so pieces of
information on the page are relevant to him, right at this moment. The
linked page may arguably be useful as a reference for someone who
already knows dub well, but it's completely obtuse to something who
doesn't know what dub is.
Even as a reference, the information isn't organized in an easily
navigable way. It's basically one giant infodump of the absolute bare
minimum information you need to remind yourself how to do a particular
task, but to someone who doesn't already know dub, it looks disorganized
and thrown together in a completely arbitrary, opaque order.
For example, the very first section talks about "global scope". What's a
"global scope" and why do I need it? Who knows, who cares, here are all
the settings that go into "global scope", you go figure it out yourself.
Immediately following is the section "sub packages". There is no
explanation of what's a "sub package" and why I might want one until the
second paragraph, which contains a single sentence that's supposed to
magically make me understand why I might want a sub package. I
basically have to read through the whole thing, digest it, connect the
dotted lines myself, before I can even have an answer to the most basic
of questions, "what is this and why should I care about it?". In the
meantime there's all kinds of random statements aimed at experienced
users, recommendations for best practices without any context or
explanation of why they're recommended (you're expected to figure it out
yourself).
The paragraph before the last code block in this section ("Sub
packages") is a typical example: "It is also possible to define the sub
packages within the root package file, but note that it is generally
discouraged to put the source code of multiple sub packages into the
same source folder." In one sentence the document has managed to (1)
introduce a possible configuration without any explanation of why one
might want to do that and (2) contradict itself by saying this is
generally discouraged. Then (3) the remainder of the paragraph goes on
to completely negate the first part of the first sentence, complete with
a code example of, I guess, what not to do? Why is all of this even
here?! If something is a discouraged practice, it sholdn't be smack in
my face right in the middle of the docs, occupying at least half of the
entire section(!). First document what I *should* do, then in a
footnote or a separate page explain what to avoid. And explain why I
might want a "sub package" instead of assuming I already know what it
is.
And on and on and on. The order of sections is, to put it mildly, hard
to follow. As an infodump, it's not suitable material to introduce
someone to dub. There's no explanation of common use cases, zero
hand-holding, and poor or missing motivation for anything. There's no
explanation of how to handle common use cases that one might encounter.
Maybe the explanation *is* in there somewhere, but I've no idea where it
is and have to essentially read through the entire thing to find it (and
hope I don't miss it).
As reference material, it's incomplete and could use better navigation.
And clearer explanation and definitions of what each config item does,
instead of 1-sentence descriptions that the reader has to collect then
somehow piece together in his head and magically guess the intent of
each feature. Also ALL corner cases must be covered thoroughly (if it's
to be a reference, it better be thorough!), as well as conceivable use
cases that someone might want but isn't supported. (And an explanation
of why it isn't supported would also be nice.)
T
--
Real men don't take backups. They put their source on a public FTP-server and
let the world mirror it. -- Linus Torvalds
