On Sunday, 21 August 2016 at 19:12:27 UTC, Andrei Alexandrescu wrote:
> On 08/21/2016 03:01 PM, Seb wrote:
>> because (1) you need less documentation (just one file to document) and
>
> Wouldn't it be better to optimize documentation for the reader instead of the writer? After all if reading is impaired, that's bound to make the maintainer unhappy even if she has fewer documents to maintain.
>
>> (2) the single file will be more tested/bullet-proof.
>
> How does that work? Aren't step-by-step documents "how to do this on Posix" and "how to do this for Windows" best tested in one environment at a time?

If in both cases the build commands would only be sth. like:

<my-fancy-build-toold> build
<my-fancy-build-toold> test
...

then there would be no need for a second Windows-only document.


>> Anyways sorry about mentioning it - I know that such (a) a change
>> shouldn't be taken lightly and it also may cause additional troubles and
>
> What troubles would there be? How were troubles taken into account when the document got modified from its initial Posix-only stance to the current state?

I was referring to switching from Makefiles to a different cross-platform tool like reggae, which bears some troubles with it due to many existing setups and infrastructure.

> Please just fix it with no debate.

Sorry, it wasn't intended as a debate, we just posted at the same time initially.

https://wiki.dlang.org/Building_under_Posix
https://wiki.dlang.org/Building_under_Windows

On Monday, 22 August 2016 at 02:34:37 UTC, Walter Bright wrote:
> On 8/21/2016 12:12 PM, Andrei Alexandrescu wrote:
>> How does that work? Aren't step-by-step documents "how to do this on Posix" and
>> "how to do this for Windows" best tested in one environment at a time?
>
> I know when I'm following step-by-step procedures, I prefer it to be specific to my case, not a catch-all one with callouts for other cases melded in.

Some users might just about know they're on Windows but have no idea what Posix is so won't know to ignore those parts or will at least be confused and intimidated. The path into using things needs to be as easy as possible.

On 8/23/2016 2:15 AM, ixid wrote:
> Some users might just about know they're on Windows but have no idea what Posix
> is so won't know to ignore those parts or will at least be confused and
> intimidated. The path into using things needs to be as easy as possible.

Sometimes I have customers that don't know what a command prompt or a subdirectory is, and I've learned to just send their money back.

On Sunday, 21 August 2016 at 16:49:53 UTC, Andrei Alexandrescu wrote:
> "Awfully categorized" is right. The initial step-by-step document I wrote for Posix got corrupted into this mess.
>
> Folks, I have in two instances asked nicely the authors or anyone else to fix this mess. I shouldn't need to worry about this stuff. Posix and Windows interspersed in the same document is not the way to go. Please fix this once and for all by splitting into two documents: one for Posix and one for Windows, thanks.

Sorry Andrei, this is the first time I've seen you talk about it.

I'll fix it when I have some time. Probably this weekend.

On 08/23/2016 10:54 AM, Jack Stouffer wrote:
> I'll fix it when I have some time. Probably this weekend.

Very much appreciated. Thanks! -- Andreui

On Tuesday, 23 August 2016 at 10:28:35 UTC, Walter Bright wrote:
> On 8/23/2016 2:15 AM, ixid wrote:
>> Some users might just about know they're on Windows but have no idea what Posix
>> is so won't know to ignore those parts or will at least be confused and
>> intimidated. The path into using things needs to be as easy as possible.
>
> Sometimes I have customers that don't know what a command prompt or a subdirectory is, and I've learned to just send their money back.

When your software is free your currency is people's attention. We really don't want to be giving out refunds.

On 8/23/2016 10:58 AM, Meta wrote:
> On Tuesday, 23 August 2016 at 10:28:35 UTC, Walter Bright wrote:
>> Sometimes I have customers that don't know what a command prompt or a
>> subdirectory is, and I've learned to just send their money back.
>
> When your software is free your currency is people's attention. We really don't
> want to be giving out refunds.

I don't like to lose any customers. They do have expectations when they pay money for a product, but I can't teach someone via email how their computer works when all they know is click & drag. I've tried, it ended badly every time.

You can't remotely teach someone to fly an F-104 when they don't know what a rudder is.

At least with D I can point them to the learn forum.

On Tuesday, 23 August 2016 at 19:59:41 UTC, Walter Bright wrote:
> On 8/23/2016 10:58 AM, Meta wrote:
>> When your software is free your currency is people's attention. We really don't
>> want to be giving out refunds.
>
> I don't like to lose any customers. They do have expectations when they pay money for a product, but I can't teach someone via email how their computer works when all they know is click & drag. I've tried, it ended badly every time.
>
> You can't remotely teach someone to fly an F-104 when they don't know what a rudder is.
>
> At least with D I can point them to the learn forum.

Yes, very true. However, getting back to the complaint of both documentation sets being in a single document: I'm experienced with box Linux-based and Windows-based systems and I still find the combined documentation annoying and a pain because I have to scroll through the Posix stuff every time to get to the Windows section.

Except, as of today the two pages have been split and it looks much better. Thanks to whoever did that.

On Tuesday, 23 August 2016 at 20:54:19 UTC, Meta wrote:
> Except, as of today the two pages have been split and it looks much better. Thanks to whoever did that.

Nothing to thank - it wasn't much work, but I did that yesterday, so it was quite funny to observe the conversation ;-)