www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Suggestion re the manual

reply Paul <pault ucora.com> writes:
I am not an expert programmer (although I work in software every 
day). I'm more of a system designer. Dlang has really made a big 
difference in our little company and we are truly grateful to 
have it. However, one thing I miss from my PHP days (I know - 
script languages - Ugh), is having public comments below each 
manual page.

Having the public post examples, gotchas, and other helpful 
information made a world of difference in learning the PHP 
language, all the while having the "source of truth" directly 
above.

Just suggesting that it might help increase adoption rates (PHP 
is very popular). Managing comments does take time, but then so 
does managing this forum.

Anyway, no ideas are bad ideas, so I felt I should post. I hope 
it is helpful.
Jun 07 2022
next sibling parent reply bauss <jj_1337 live.dk> writes:
On Tuesday, 7 June 2022 at 21:28:30 UTC, Paul wrote:

 I am not an expert programmer (although I work in software 
 every day). I'm more of a system designer. Dlang has really 
 made a big difference in our little company and we are truly 
 grateful to have it. However, one thing I miss from my PHP days 
 (I know - script languages - Ugh), is having public comments 
 below each manual page.

 Having the public post examples, gotchas, and other helpful 
 information made a world of difference in learning the PHP 
 language, all the while having the "source of truth" directly 
 above.

 Just suggesting that it might help increase adoption rates (PHP 
 is very popular). Managing comments does take time, but then so 
 does managing this forum.

 Anyway, no ideas are bad ideas, so I felt I should post. I hope 
 it is helpful.


Personally, I don't like it. I don't think good documentation 
needs comments to explain the content.

The reason why it's good for PHP is mostly because of how 
unintuitive and inconsistent it really is sometimes.

As you said yourself, it's good for gotchas etc.

D doesn't really have any gotchas in that sense since it's much 
more strict, not just in the sense of its language, but also how 
the standard library is written.

Most gotchas in PHP stem from inconsistent function names, 
arguments and the fact it's dynamic typing.

D has very consistent naming of functions, order of arguments and 
it's static typed.

Most other language documentations don't have a comment section 
either and probably because they're documented well too.

While PHP has improved and keeps improving, then it still let's 
most of is garbage linger around.
Jun 08 2022
parent reply Paul <pault ucora.com> writes:
On Wednesday, 8 June 2022 at 08:26:02 UTC, bauss wrote:

 On Tuesday, 7 June 2022 at 21:28:30 UTC, Paul wrote:

 I am not an expert programmer (although I work in software 
 every day). I'm more of a system designer. Dlang has really 
 made a big difference in our little company and we are truly 
 grateful to have it. However, one thing I miss from my PHP 
 days (I know - script languages - Ugh), is having public 
 comments below each manual page.

 Having the public post examples, gotchas, and other helpful 
 information made a world of difference in learning the PHP 
 language, all the while having the "source of truth" directly 
 above.

 Just suggesting that it might help increase adoption rates 
 (PHP is very popular). Managing comments does take time, but 
 then so does managing this forum.

 Anyway, no ideas are bad ideas, so I felt I should post. I 
 hope it is helpful.


 Personally, I don't like it. I don't think good documentation 
 needs comments to explain the content.

 The reason why it's good for PHP is mostly because of how 
 unintuitive and inconsistent it really is sometimes.

 As you said yourself, it's good for gotchas etc.

 D doesn't really have any gotchas in that sense since it's much 
 more strict, not just in the sense of its language, but also 
 how the standard library is written.

 Most gotchas in PHP stem from inconsistent function names, 
 arguments and the fact it's dynamic typing.

 D has very consistent naming of functions, order of arguments 
 and it's static typed.

 Most other language documentations don't have a comment section 
 either and probably because they're documented well too.

 While PHP has improved and keeps improving, then it still let's 
 most of is garbage linger around.


I see your point Bauss. I suppose I am not yet experienced enough 
with D.

Here is an example. Working with one of our programmers, he could 
not understand the following (sorry for my newbie simplistic 
example and understanding of D):

if ( a_name.exists ) ...

Where a_name is a string argument passed into the function. He 
felt that it was checking if the string has a value and could not 
understand why. It was a surprise to find that "exists" is 
actually a uniquely named D function that actually means 
"fileexists". Same with copy and remove.

Later, a more senior developer suggested we alias these names to 
be more readable, and easier to search for (we have a mix of D 
code, JS, and even our own class methods with similar names).

Maybe public comments like this within the manual could help with 
understanding and help improve the accessibility and adoption of 
D?

Regardless, D is wonderful, and we are thankful to have it. We 
hope D achieves widespread adoption it so that our company can 
rest assured that the project will live on. Sadly, a big deciding 
factor is risk mitigation (particularly by venture capitalists) 
and access to experience developers, who are all looking at this 
in the same way. It is very frustrating to hear "Why would we 
want to code in D? Who uses D?" when we know with 100% certainty 
that D significantly reduces our development time, and increases 
the reliability and maintainability of our software. And 
likewise, when a programmer says "I cannot understand the manual. 
It seems to be written for D experts only" it feels like a punch 
to the gut.

D is brilliant once you get into it. We will do whatever we can 
to help it spread.

Thank you for listening.
Jun 08 2022
next sibling parent Guillaume Piolat <first.last gmail.com> writes:
On Wednesday, 8 June 2022 at 18:34:20 UTC, Paul wrote:

 Later, a more senior developer suggested we alias these names 
 to be more readable, and easier to search for (we have a mix of 
 D code, JS, and even our own class methods with similar names).


Here is a simple Phobos trick (courtesy of Adam) that I learned 
after much time grieving about std.file short names.

**Tip:** Use `static import file = std.file;` instead of `import 
std.file`;

https://d.godbolt.org/z/cq5xejdTx

Now you have:

    - `file.read`
    - `file.write`
    - `file.exists`


It's bad that Phobos takes over the namespace with 
non-descriptive names like read/write/exists, when names like 
fileExists/fileRead/fileWrite would be better for code completion 
and discoverability. And indeed, Phobos has a lot of 
undiscoverable things because the names don't have a prefix.

But you can keep things readable anyway with `static import`.
Jun 09 2022
prev sibling next sibling parent reply Guillaume Piolat <first.last gmail.com> writes:
On Wednesday, 8 June 2022 at 18:34:20 UTC, Paul wrote:

 It is very frustrating to hear "Why would we want to code in D? 
 Who uses D?" when we know with 100% certainty that D 
 significantly reduces our development time, and increases the 
 reliability and maintainability of our software.


Welcome to D!
Do not hesitate to speak about your experiences in the D Blog :)
Jun 09 2022
parent reply Paul <pault ucora.com> writes:
On Thursday, 9 June 2022 at 14:03:43 UTC, Guillaume Piolat wrote:

 On Wednesday, 8 June 2022 at 18:34:20 UTC, Paul wrote:

 It is very frustrating to hear "Why would we want to code in 
 D? Who uses D?" when we know with 100% certainty that D 
 significantly reduces our development time, and increases the 
 reliability and maintainability of our software.


 Welcome to D!
 Do not hesitate to speak about your experiences in the D Blog :)


I am Googling for research on how many (most?) people typically 
learn a new programming language. Some interesting hits come up:

https://www.google.com/search?ie=UTF-8&client=ms-android-telus-ca-revc&source=android-browser&q=research+on+how+most+people+learn+a+new+programming+language

Without yet digging into the research, I would assume it is a 
cost vs return equation based on needs and motivation. For 
myself, at first I do not yet know if I want to "commit" to the 
language, and so I want to keep my learning time (cost) to the 
minimum necessary to assess if this is the language I need. I 
would have to think about what criteria I am using to assess the 
new language. Again, this may be determined by what is motivating 
me to do so. Is it for myself? For my boss? A specific technical 
challenge? Is this a long or short term project? How important is 
this?

It seems I need to be "drawn in", easily at first, but with 
gradual increasing levels of depth and levels of commitment. At 
each step, my cost vs return balance must be kept positive, 
assuming I am in control of my decisions.

I know what I wanted: A compiled language that will be powerful, 
clear, concise, consistent, and save countless wasted hours 
dealing with the challenges of C++ and other languages. D does 
this very well. Who wouldn't want all this, andyet why is it 
difficult for me to convince others, and to get that level of 
commitment to read the books, invest the time? One concern may be 
"Who uses D?" "How will D help *my* career?" I would argue that 
it can and it will help their career, even if D is not a language 
the programmer will use in their next job. It changes the way one 
thinks about programming. It focuses on removing waste, and that 
is a mindset valuable in any environment. D helps make us better 
programmers, no matter what language we use.

Sorry, just thinking out loud here. Maybe it will spark some 
ideas.
Jul 09 2022
parent Paul <pault ucora.com> writes:
This is interesting:

https://m-cacm.acm.org/magazines/2022/3/258914-technical-perspective-how-do-experts-learn-new-programming-languages/fulltext
Jul 11 2022
prev sibling next sibling parent matheus <matheus gmail.com> writes:
On Wednesday, 8 June 2022 at 18:34:20 UTC, Paul wrote:

 ...
 Here is an example. Working with one of our programmers, he 
 could not understand the following (sorry for my newbie 
 simplistic example and understanding of D):

 if ( a_name.exists ) ...

 Where a_name is a string argument passed into the function. He 
 felt that it was checking if the string has a value and could 
 not understand why. It was a surprise to find that "exists" is 
 actually a uniquely named D function that actually means 
 "fileexists". Same with copy and remove.

 ...


I know this is an example and maybe there is more things going 
around, but still using this case, it isn't a matter of naming 
things better? - For example:


 if ( a_name.exists ) ...


Well... yes the "a_name" as is (Or another name chosen) may not 
help with the context, but:

if (myfile.exists) {}

I think that with "myfile" the context is clear now and the 
method/property "exists" is deductible from it and what will be 
expected.

Matheus.
Jun 09 2022
prev sibling parent harakim <harakim gmail.com> writes:
On Wednesday, 8 June 2022 at 18:34:20 UTC, Paul wrote:

 I see your point Bauss. I suppose I am not yet experienced 
 enough with D.

 Here is an example. Working with one of our programmers, he 
 could not understand the following (sorry for my newbie 
 simplistic example and understanding of D):


The D community so far has said you just need to learn it and the 
documentation makes sense. I think that summary speaks volumes 
about missing the point of documentation but that is the reality 
in D. You have to learn it from books and forum and then you 
pretty much don't need the documentation.

Just a few days ago, I actually posted about documentation, among 
other things, but I threw 80% of that reply away because I'm 
trying to be less negative on the forum. Here is the excerpt:

```
In fact, I'm on the forum right now because I was looking for a 
map function in D. Here it is:
https://dlang.org/library/std/algorithm/iteration/map.map.html.

The map function is there and it works really well. But go ask 10 
of your co-workers (that haven't used D) how this function works 
and maybe 2 or 3 can even guess something close. I don't even 
know for sure how I specify the mapping function (sometimes it's 
a function, sometimes it's a string) but with a bit of trial and 
error, I'll figure it out. There's not even an example of usage 
in the documentation.
```

The documentation is not good is not a way to learn D, although 
it is somewhat useful. If you want your team to learn and get 
familiar with D enough to use the documentation, I would suggest 
you get Andrei's and Adam's books. There are other good books as 
well I'm sure, but I have not read them. Some sit in my Amazon 
cart where I covet them from time to time. ;) You might find 
comments about them being out of date, but by the time your 
colleagues are done with them, they will be able to understand 
the documentation.

I hate to bug people on the forum, but I know if I have a 
question, I will get a response by the next day, but usually a 
lot faster than that.

So if I were you, I would solve the immediate problem by getting 
and distributing those book as well as inviting your colleagues 
onto the forum if they have questions you can't answer.

In the medium term, you could start a knowledge base or 
documentation site or maybe join one of the dozens of others that 
undoubtedly exist.

The long term problem is harder to address. Until building 
documentation, tools and library is sustainable, people won't do 
it. I have spent a lot of effort on projects that die (including 
D programs, as it happens) and I have a lot going on in my life. 
It's going to take a large effort to establish clear goals and 
visions with a known way to work on them or it may take forking 
the language and leaving one stable for a bit before people 
decide. I hope that happens before another language enters D's 
odd niche.
Jun 09 2022
prev sibling next sibling parent reply =?UTF-8?Q?Ali_=c3=87ehreli?= <acehreli yahoo.com> writes:
On 6/7/22 14:28, Paul wrote:


 Dlang has really made a big difference in
 our little company


Can you share more information?

Regarding "access to experience[d] developers" that you mentioned, I 
always thought one benefit of smaller communities like D is that you 
know its members find it very useful and in many cases are looking for 
opportunities to work with it. So, although the pool of D programmers is 
small, "you will code in D" should make it easy to get them. :)

Additionally, as John Colvin has been saying, the average strength of a 
programmer on these forums is likely higher than larger communities. (I 
hope I paraphrased it correctly.)

Ali
Jun 08 2022
parent reply Paul <pault ucora.com> writes:
On Wednesday, 8 June 2022 at 19:27:58 UTC, Ali Çehreli wrote:

 On 6/7/22 14:28, Paul wrote:


 Dlang has really made a big difference in
 our little company


 Can you share more information?


Our company (www.ucora.com) created GamePlanPro in D 7 years ago. 
GPP is a web-based workflow platform used by a majority of our 
customers. Quotes, work orders, invoices, asset management, 
scheduling, periodic maintenance, reporting, user created 
procedures and forms, CRM, and user management. We are fully 
invested in D and we hope to see it grow in popularity.

I wondered if user comments linked to the manual pages (similar 
to Guillaume's reply) might be a catalyst for easier adoption, a 
place to show code examples, in context, without having to 
consume much of the D team's time, and without having to search 
the forum. This may make entry by programmers who are unfamiliar 
with D easier.
Jun 09 2022
parent reply Steven Schveighoffer <schveiguy gmail.com> writes:
On 6/9/22 5:28 PM, Paul wrote:

 Our company (www.ucora.com) created GamePlanPro in D 7 years ago. GPP is 
 a web-based workflow platform used by a majority of our customers. 
 Quotes, work orders, invoices, asset management, scheduling, periodic 
 maintenance, reporting, user created procedures and forms, CRM, and user 
 management. We are fully invested in D and we hope to see it grow in 
 popularity.


This sounds amazing! I've been doing quite a bit of the same (I gave a 
presentation [in 2018](https://dconf.org/2018/talks/schveighoffer.html) 
on my efforts to port a php tracking system to vibe-d, it's still ongoing).

Did you use an OTS web framework (vibe/hunt) or build your own? I'm just 
curious.

-Steve
Jun 09 2022
parent reply Rob T <alanb ucora.com> writes:
On Thursday, 9 June 2022 at 21:35:49 UTC, Steven Schveighoffer 
wrote:

 On 6/9/22 5:28 PM, Paul wrote:

 Our company (www.ucora.com) created GamePlanPro in D 7 years 
 ago. GPP is a web-based workflow platform used by a majority 
 of our customers. Quotes, work orders, invoices, asset 
 management, scheduling, periodic maintenance, reporting, user 
 created procedures and forms, CRM, and user management. We are 
 fully invested in D and we hope to see it grow in popularity.


 This sounds amazing! I've been doing quite a bit of the same (I 
 gave a presentation [in 
 2018](https://dconf.org/2018/talks/schveighoffer.html) on my 
 efforts to port a php tracking system to vibe-d, it's still 
 ongoing).

 Did you use an OTS web framework (vibe/hunt) or build your own? 
 I'm just curious.

 -Steve


I'll out myself as some one who is also associated with Ucora, 
I'm one of the original founders. I was the one who discovered D 
and eventually adopted it as our choice language. To answer your 
question, yes we did consider Vibe, it was a long time ago, and 
at that time it wasn't really suitable for embedding into our 
applications. We prefer fully embedded as opposed to separate. I 
think a lot of work was eventually done to make Vibe more 
suitable to integrate into a package, and we should revisit 
because we are looking for an alternative. The tool we're still 
using (tntnet) is based on C++ and runs as a separate process. 
it's not what we want but has worked well enough that no one took 
the time to move one to better alternatives. The situation for us 
is changing, we really do want an embedded solution.
Jun 09 2022
next sibling parent reply Adam Ruppe <destructionator gmail.com> writes:
On Thursday, 9 June 2022 at 22:23:24 UTC, Rob T wrote:

 We prefer fully embedded as opposed to separate.


What do you mean by embedding here?
Jun 09 2022
parent reply Rob T <alanb ucora.com> writes:
On Thursday, 9 June 2022 at 22:53:04 UTC, Adam Ruppe wrote:

 On Thursday, 9 June 2022 at 22:23:24 UTC, Rob T wrote:

 We prefer fully embedded as opposed to separate.


 What do you mean by embedding here?


What I mean by that is incorporate the http code directly into 
our application and compile it into a single executable binary, 
ie no separate process for handling https requests. Having said 
that, ideally the http code should be in the form of a standard 
library that we tap into, just as we do with any other library.

What we do not want or need is a traditional style http server 
process that is feeding typical web apps, we're not running a 
typical web app, the web side is simply the user interface, 
that's the only use we have for it.
Jun 09 2022
parent reply Adam Ruppe <destructionator gmail.com> writes:
On Friday, 10 June 2022 at 00:35:17 UTC, Rob T wrote:

 What I mean by that is incorporate the http code directly into 
 our application and compile it into a single executable binary


Huh, I'm surprised you had trouble with vibe since it works that 
way too.

Of course, I have my own D libraries (the oldest continually 
maintained web code in D) which is not just embedded, it is a 
single source file http server with no extra dependencies!

...but I never bothered doing https support since I prefer to use 
the outer proxy server for that. Probably about 50 lines to add 
it, maybe I will one of these days.
Jun 09 2022
next sibling parent reply Rob T <alanb ucora.com> writes:
On Friday, 10 June 2022 at 00:59:00 UTC, Adam Ruppe wrote:

 On Friday, 10 June 2022 at 00:35:17 UTC, Rob T wrote:

 What I mean by that is incorporate the http code directly into 
 our application and compile it into a single executable binary


 Huh, I'm surprised you had trouble with vibe since it works 
 that way too.

 Of course, I have my own D libraries (the oldest continually 
 maintained web code in D) which is not just embedded, it is a 
 single source file http server with no extra dependencies!

 ...but I never bothered doing https support since I prefer to 
 use the outer proxy server for that. Probably about 50 lines to 
 add it, maybe I will one of these days.


Yeah last I remember Vibe was being re-coded to work like a 
library rather than only as an http server, like I said it was a 
long time ago when I was looking around at Vibe. I'll take a good 
look again, it sounds promising. I'll also take a look at your 
library as well, this must be it 
https://code.dlang.org/packages/arsd-official%3Ahttp

We also use a proxy (haproxy), main reason is we still have to 
support ipv4, and a proxy is ideal solution for a server with 
only 1 ipv4 address. We run most things today as lxc 
containerised appliances, one server will have many containers. A 
proxy however does come with a single point of failure issue, it 
would be more ideal for ipv6 enabled clients to by-pass the proxy 
and go directly to each container.
Jun 10 2022
parent reply Adam D Ruppe <destructionator gmail.com> writes:
On Friday, 10 June 2022 at 08:02:16 UTC, Rob T wrote:

 Yeah last I remember Vibe was being re-coded to work like a 
 library rather than only as an http server, like I said it was 
 a long time ago when I was looking around at Vibe.


Oh, its weird static constructor thing it used to do.



 I'll also take a look at your library as well, this must be it 
 https://code.dlang.org/packages/arsd-official%3Ahttp


That's my client, the server is in the cgi.d file,

https://code.dlang.org/packages/arsd-official%3Acgi

It does a LOT but I only documented some of it in there. I 
originally wrote it in 2008 to transition some PHP code over to 
D, then over the years it got more and more, including a full 
http server, websocket support, and some fancy code generator 
stuff in addition to the cgi, fastcgi, etc. interfaces. There's 
several benefits to following the old cgi architecture though 
including being able to scale up and down fairly easily so I 
still suggest people follow that style when using the embedded 
http server, but of course you can do things differently if you 
like just configure for threads or a smaller process pool, etc. 
Feel free to email me with questions.

Other modules in the arsd package offer other things I've needed 
over the years like database interfaces, a server-side DOM 
implementation, and then other things like gui application too 
too that isn't web related lol.


 A proxy however does come with a single point of failure issue, 
 it would be more ideal for ipv6 enabled clients to by-pass the 
 proxy and go directly to each container.


I've never tested ipv6 either. I'm sure not hard to add if 
needed, but my isp still doesn't support it anyway so it all 
useless to me! lol
Jun 10 2022
parent Rob T <alanb ucora.com> writes:
On Friday, 10 June 2022 at 12:00:02 UTC, Adam D Ruppe wrote:

 I've never tested ipv6 either. I'm sure not hard to add if 
 needed, but my isp still doesn't support it anyway so it all 
 useless to me! lol



As for ipv6, you should try to somehow get it working in your 
area if that is possible, it really does change how things are 
done, some of the old ways simply don't apply anymore, eg port 
forwarding, proxies, and even LAN firewalls do not make as much 
sense like they used to. My understanding is that all new 
infrastructure being rolled out for 5G networks and high speed 
switching do not even support ipv4 at all, although maybe as 
packets transported over ipv6, the general trend is to ditch ipv4 
completely where ever possible.

BTW Thanks for the responses! It all sounds good and I will try 
out your library as well as vibe as soon as I can. I look forward 
to finally getting rid of the last of the C/C++ code that we 
have, it'll be one of those occasions where we will have a small 
celebration over it, no joke :)
Jun 10 2022
prev sibling parent Paolo Invernizzi <paolo.invernizzi gmail.com> writes:
On Friday, 10 June 2022 at 00:59:00 UTC, Adam Ruppe wrote:

 On Friday, 10 June 2022 at 00:35:17 UTC, Rob T wrote:

 What I mean by that is incorporate the http code directly into 
 our application and compile it into a single executable binary


 Huh, I'm surprised you had trouble with vibe since it works 
 that way too.

 Of course, I have my own D libraries (the oldest continually 
 maintained web code in D) which is not just embedded, it is a 
 single source file http server with no extra dependencies!

 ...but I never bothered doing https support since I prefer to 
 use the outer proxy server for that. Probably about 50 lines to 
 add it, maybe I will one of these days.


Here we are using your code as a base for our single process 
backend (well, copy-pasting only the needed parts of it).

It was easier to add SSL support directly using Deimos than 
configuring NGINX. But we don't have big workloads to deal with.

/P
Jun 10 2022
prev sibling parent reply Paul <pault ucora.com> writes:
Hi Steven

GPP would not have been possible without D. We know this because 
we created a previous workflow system in C++. It was a painful 
slow slog to develop. Once you go with D, you can never go back. 
I would hazard a guess of it making us 10 times more efficient at 
coding, however I don't have hard numbers to prove this. Still, 
if anyone sees a demo of GPP, they would be shocked to find that 
it was created with such a tiny team. Previously, we came from a 
background of c, c++, PHP, Javascript, and some other languages 
so old I would be embarrassed to mention them (such as Pascal!) 
Our lines of code alone is reduced by at last a factor of 10 with 
D.

And yet, even someone within our own team will question why we 
are using such an obscure language. "Why aren't we using nodejs? 
Everyone is using it." (It breaks me to hear that.) So, nothing 
would make us happier than to see D grow in popularity. Our wish 
is to see D reach out and draw people in. To make it easy for 
them to get started, without ever compromising the core vision. 
It really should be the next dominant compiled programming 
language.

How to do this? I am the furthest from an expert. There must be 
examples to learn from, on how others have succeeded with 
inferior products. And how to avoid it being polluted by people 
who don't really understand the core reasoning behind the design 
choices? Always a challenge.
Jun 09 2022
parent Guillaume Piolat <first.last gmail.com> writes:
On Thursday, 9 June 2022 at 23:13:06 UTC, Paul wrote:

 How to do this? I am the furthest from an expert. There must be 
 examples to learn from, on how others have succeeded with 
 inferior products. And how to avoid it being polluted by people 
 who don't really understand the core reasoning behind the 
 design choices? Always a challenge.


Open source libraries tend to attract people to languages.
The more ecosystem we have, the more people can disrupt legacy 
verticals.
People don't change their mind until you compete with them. :)

Also getting on Orgs-using-D page, filing bugs, going to DConf.
Telling your story like this is very inspiring!
Jun 09 2022
prev sibling next sibling parent Rob T <alanb ucora.com> writes:
WRT "exists" being difficult to discover, it's important to keep 
in mind that D is a generic programming language. The "exists" 
concept won't necessarily apply to files, which make prefixing 
much more desirable than embedding the "file" name directly into 
the function (or template) name.

As an example outside from programming, consider how domain names 
are organised,

toplevel = dlang.org
sub-level = forum.dlang.org

We could create a brand new domain, forumdlang.org but that's not 
a great idea do to. Same idea as with exists.

The basic issue is that not much has progressed with programming 
languages over the last century (yes I'm joking) we still use 
text editors to program with (IDE's are noth more than glorified 
text editors), and a side effect of that is searching on text 
strings is kinda silly if you know what I mean.

Really the best way to view a programming language is as if it 
were a strand of DNA, it's something to manipulate, but it has to 
be done carefully otherwise you end up with a lot of warts. We 
need much better tools, one day we may have them, but I'll 
probably in the grave before that ever happens.
Jun 09 2022
prev sibling next sibling parent Rob T <alanb ucora.com> writes:
On Tuesday, 7 June 2022 at 21:28:30 UTC, Paul wrote:


 Having the public post examples, gotchas, and other helpful 
 information made a world of difference in learning the PHP 
 language, all the while having the "source of truth" directly 
 above.


I think that's a great idea *if* done properly. For example we'd 
have to be careful to ensure that the comments are not misleading 
or incorrect, the comments should NOT directly be a part of the 
documentation, which should always remain a separate item.

How to manage and design such a thing needs some thought, but I 
see no reason why it's not possible. We could for example, only 
allow known D members as contributors to ensure quality. We could 
use a database with links to the separate comments to keep the 
two spaces complete separate (except we do need the links in 
there somehow).
Jun 09 2022
prev sibling next sibling parent reply Adam D Ruppe <destructionator gmail.com> writes:
On Tuesday, 7 June 2022 at 21:28:30 UTC, Paul wrote:

 However, one thing I miss from my PHP days (I know - script 
 languages - Ugh), is having public comments below each manual 
 page.


One thing I missed about php was going to like php.net/trim so i 
made my website dpldocs.info/strip etc. to bring it to D. My site 
there now runs its generator on dub packages too to help search 
across the ecosystem.

I need to clean some things up since I keep running out of disk 
space as there's 100 different versions of win32 needlessly 
copied etc. lol. I'm at 99% again so need to stop procrastinating 
at some point.

But once I do that, adding a comments field to each symbol would 
be technically pretty easy to do, I could even borrow some code 
from my beloved dwidder website and just paste it in!

The hard part would probably be spam control. The dwitter site 
makes you type a magic word (which it tells you on the page) and 
it seemed ok but it also isn't on search engines whereas the 
dpldocs.info site is, so that'd probably be different.

I'm of the opinion that most the comments should generally be in 
the docs themselves, and then you can submit via PR which means 
there's a review step and much less odds of spam bots hitting it. 
Also, as a user, reading through a bunch of random comments of 
varying quality just often feels bad; there's always a few gems 
of comments in there but looking through a bunch of lower quality 
ones is not as nice as the answer just plain being there. 
Comments would probably also be exempt from version checks 
meaning they can fall out of date. Of course, seeing the date on 
the comment gives people a clue it might be old.

Nevertheless, maybe I'll do it just as an experiment. Can always 
undo it later if it has more spam than value.
Jun 10 2022
parent reply Paul <pault ucora.com> writes:
On Friday, 10 June 2022 at 12:13:58 UTC, Adam D Ruppe wrote:

 The hard part would probably be spam control. The dwitter site 
 makes you type a magic word (which it tells you on the page) 
 and it seemed ok but it also isn't on search engines whereas 
 the dpldocs.info site is, so that'd probably be different.


Maybe only forum users would be permitted to post comments 
against the manual? Then it would be no different than the 
control afforded by the forum we are chatting on now.

We may be surprised by how few people would have the courage to 
post anyway.

Regardless, I am thankful the group is at least considering it. 
It says a lot about how important D is to all of you. Let me know 
if there is anything I can do to help. If you feel it is 
appropriate and helpful, maybe it is time to for us ask to be on 
your list of companies using D? We have a number of prominent 
customers: www.ucora.com/clients

Thank you
Jun 10 2022
next sibling parent James Blachly <james.blachly gmail.com> writes:
On Saturday, 11 June 2022 at 04:30:17 UTC, Paul wrote:

 Regardless, I am thankful the group is at least considering it. 
 It says a lot about how important D is to all of you. Let me 
 know if there is anything I can do to help. If you feel it is 
 appropriate and helpful, maybe it is time to for us ask to be 
 on your list of companies using D? We have a number of 
 prominent customers: www.ucora.com/clients

 Thank you


I’m not sure who is in charge of the website (Mike Parker?) but I 
am bumping thread for visibility — certainly Ucora should be 
added!
Jun 26 2022
prev sibling parent Bastiaan Veelo <Bastiaan Veelo.net> writes:
On Saturday, 11 June 2022 at 04:30:17 UTC, Paul wrote:

 maybe it is time to for us ask to be on your list of companies 
 using D? We have a number of prominent customers: 
 www.ucora.com/clients

 Thank you


You definitely should be on that list. No need to wait and hope 
to be included, though, just do it yourself! Press the “improve 
this page” link on the top right corner, and follow the 
instructions (you might need a Github account). You’ll be 
creating a pull request. The CI will automatically build a copy 
of the site so you can preview it. We have two PR managers aside 
from several others with merge rights, one of them will have a 
look at it and point you in the right direction if anything is 
lacking. If you get stuck don’t hesitate to ask here.

By the way, that link is on most pages of dlang.org, including 
the documentation, and it is the easiest way to bring about 
improvements. If anybody sees a way to make the documentation 
better, she should not hesitate to do so :-) It really is all up 
to us, the users.

— Bastiaan.
Jun 26 2022
prev sibling next sibling parent reply Bastiaan Veelo <Bastiaan Veelo.net> writes:
On Tuesday, 7 June 2022 at 21:28:30 UTC, Paul wrote:

 One thing I miss from my PHP days (I know - script languages - 
 Ugh), is having public comments below each manual page.

 Having the public post examples, gotchas, and other helpful 
 information made a world of difference in learning the PHP 
 language, all the while having the "source of truth" directly 
 above.

 Just suggesting that it might help increase adoption rates (PHP 
 is very popular). Managing comments does take time, but then so 
 does managing this forum.

 Anyway, no ideas are bad ideas, so I felt I should post. I hope 
 it is helpful.


Andrei’s alternative one-page-per-function documentation had a 
user comment section on every page at one stage. IIRC that 
feature wasn’t used much and when it was the comment wasn’t very 
useful.

But we have a method for anybody to improve any page of the 
documentation with examples, See_Also links and (if you ask me) 
even smart suggestions [like this 
one](https://forum.dlang.org/post/agtmbgfigomzqqvpxwty forum.dlang.org): it is
the “improve this page” link at the top of every page.

This is what I would suggest if the documentation doesn’t give an 
answer right away: ask on the learn forum, then come back to the 
documentation and see if that additional knowledge can be 
incorporated in the text. I think this is a good way to make 
things better.

— Bastiaan.
Jun 26 2022
parent zjh <fqbqrr 163.com> writes:
On Sunday, 26 June 2022 at 17:03:50 UTC, Bastiaan Veelo wrote:


 This is what I would suggest if the documentation doesn’t give 
 an answer right away: ask on the learn forum, then come back to 
 the documentation and see if that additional knowledge can be 
 incorporated in the text. I think this is a good way to make 
 things better.

 — Bastiaan.



I have a blog and have gathered some links (both in `Chinese and 
English`). I hope that the `'d'` website `home page` can give me 
a `link location`.
Jun 26 2022
prev sibling parent Walter Bright <newshound2 digitalmars.com> writes:
One possibility is to, for each page, set a link to a thread on the n.g. for 
that page. This would not require any changes to our setup.

Those threads would also be moderated so any off-topic posts are removed.
Jul 08 2022