H. S. Teoh 
Posted in reply to bachmeier
| 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
|
Permalink
Reply
