On Monday, 17 February 2020 at 18:48:25 UTC, Andre Pany wrote:
> On Monday, 17 February 2020 at 15:09:39 UTC, bachmeier wrote:
>> On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
>>> This thread is a place to collect your documentation pain in one place.
>>
>> I once tried to use std.socket:
>> https://dlang.org/phobos/std_socket.html
>>
>> Although it does link to a couple of examples, they don't have any explanation, so I gave up. An example where you're up and running in five minutes using Dub would be really nice. It's pretty clear that the documentation for std.socket assumes the user has learned sockets programming in another language before coming to D. We should remove that prerequisite.
>
> Adam D. Ruppe wrote a very good socket tutorial. You can find it here http://dpldocs.info/this-week-in-d/Blog.Posted_2019_11_11.html
>
> Kind regards
> Andre

That looks pretty good. It would have to be incorporated into our official docs though, at least by providing a link.

On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
>

The elephant in the room is the DMD codebase. Examples:

1. https://dlang.org/phobos/dmd_apply.html

Empty page, with no explanation of what is the purpose of the page

2. https://dlang.org/phobos/dmd_attrib.html

Most of the documentation is non-existent, lacking or insufficient to understand what happend

3. https://dlang.org/phobos/dmd_expression.html

Most classes have no explanation. I would expect that each class would be followed by some pieces of code that highlight to what code the class maps

4. https://dlang.org/phobos/dmd_traits.html

It's missing documentation for the single most important function in the file: semanticTraits which does semantic analysis for `__traits()`

These are just a few examples, but the dmd codebase is full of such examples. In addition, now that dmd as a library is available, things are worse because people have no way of using it effectively since they cannot understand what's happening there. Moreover, it is impossible to attract new contributors when a complex piece of software is severely underdocumented.

Besides documenting this code, I think it is necessary in some situations to refactor the code so that we can highlight the documentation. For example, the traits file in dmd (link number 4) contains a single function `semanticTraits` which has 1500 lines of code and contains the whole traits semantic logic organized as if/else branches. The documentation for those branches will not be publicly available, so we must refactor the code to use separate functions. This will make the code cleaner and help us with documentation which is a great plus.
I gave this example because it is typical for a lot of situations in the dmd codebase. So not only it is a great chance to improve the documentation of dmd, but also to make the codebase more modern.

On Monday, 17 February 2020 at 13:55:57 UTC, Panke wrote:
[...]
>> We need documentation in particular on using Dub with mixed language projects. The obvious case is C and D, but one of our strengths is interoperability with basically all languages, so we should have examples showing how to use Dub with projects containing Fortran, Python, Lua, etc.
>
> I'd second this. Figuring out how sub packages work, how to structure a project into different interdependent sub packages, how to fetch dependencies (dub upgrade does not work recursively :() took way too long coming back to D.
>
> Generally a bit of best practice guidelines would be useful, see for example the my current question in the learn forum.

Yes better docs for DUB!
With as many - as possible - use case examples.

I think there are two ways of looking at the documentation: from the expert's eyes and the beginner's eyes.
I can provide feedback from the latter:
It takes some time to learn how to navigate in the library reference. But this comes with time. (and also with my inpatiance, since I am the "click a lot, read in detail later" type of guy).
What I lacked most was Ali's book. It answered many questions (especially regarding ranges). So for beginners, a more detailed tutorial (or a more prominent link to Ali's book) would be great.
Yes, sometimes, I find something in the wiki. There are some tutorials and some cookbooks. However, the information is scattered, sometimes outdated. Scattering of the information is even worse if I think about random tutorials or blogs on the internet.
The language reference is sometimes challenging to read (again for beginners). They have essential examples, but if you don't have the experience, it is sometimes tough to utilize the provided information and incorporate it into your code. My workflow usually involves a simple feature, which I then try to use; however, a simple one-liner does not cover my problem. On the other hand, too exhaustive examples will clutter the documentation.

For beginners, a more used wiki with concentrated information would be great.
However this is a D-Community solution. (and maybe i am wrong. Maybe the wiki is great and I am not long enough around to read it threw).

On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
> If you feel the urge to wax philosophical on something you see here, please start a new thread and do all the philosophical waxing you want there. Let's keep this one focused on listing specific documentation issues. Do feel free to expand on any post here with information you think is relevant.
>
> Thanks!

A timeline of current language changes would be nice. What is currently deprecated and when will it be removed, what can be found under `dmd -preview=?` and when it will be part of the language or if it is just under consideration.

On Tuesday, 18 February 2020 at 15:42:18 UTC, Jan Hönig wrote:
> For beginners, a more used wiki with concentrated information would be great.

I strongly agree with this. D's website is oriented towards search, which is a good way to find information if you know what you're looking for, but that's hardly optimal for a beginner. For some reason our wiki isn't used much, so we only have ourselves to blame.

Maybe part of a documentation improvement initiative is finding ways to encourage wiki contributions contribute more to the wiki. Maybe it's because people think you need special authority to post things there. Honestly, there's a lot of stuff in the learn forum that deserves to be organized and put on the wiki IMO.

The important question is: What is not on the wiki that should be there?

On Mon, Feb 17, 2020 at 12:16:26PM +0000, Mike Parker via Digitalmars-d wrote: [...]
> This thread is a place to collect your documentation pain in one place. I'm about to publish a blog post announcing this (a few minutes after I hit 'Send' on this post):
> 
> http://dlang.org/blog/2020/02/17/news-update-swag…on-help-and-more/
> 
> As I mention there, we need you to be as specific as you can. What, specifically, is missing? What is unclear? What is incorrect? Give as much detail as you can. We want to be able to gather this info and define specific documentation tasks that anyone can step in and complete with the information provided.
[...]

std.windows.registry does not have any docs.  The website doesn't even have a link for it! (And going to the page by editing the URL manually brings up a page with no docs for any symbol.)

Note that the code itself *does* have docs; the problem is that the website docs are generated on Posix but all symbols in this module are under version(Windows).  We seriously need to generate docs for *all* platforms, not just the one being used to generate them!

(The other std.windows.* modules have the version(StdDoc) hack, but that's seriously b0rken because what's used to generate docs is different from what actually compiles, meaning any mistakes will not be caught by CI, code examples are not compile-checked, etc..)


T

-- 
People tell me that I'm skeptical, but I don't believe them.

On Tuesday, 18 February 2020 at 18:39:57 UTC, H. S. Teoh wrote:
> std.windows.registry does not have any docs.

http://dpldocs.info/locate/?searchTerm=std.windows.registry


This is one of the big reasons why I decided *against* using dmd for my doc generation thing - it actually follows `version` rules which is necessary for compiling, but a bad thing for docs! So instead I did a separate parser.

Join me and together we rule the Dalaxy with good documentation!

On 2/18/20 10:59 AM, Panke wrote:
> A timeline of current language changes would be nice. What is currently deprecated and when will it be removed, what can be found under `dmd -preview=?` and when it will be part of the language or if it is just under consideration.

Seconding this as CRITICAL as the language evolves

On Tue, Feb 18, 2020 at 07:08:56PM +0000, Adam D. Ruppe via Digitalmars-d wrote:
> On Tuesday, 18 February 2020 at 18:39:57 UTC, H. S. Teoh wrote:
> > std.windows.registry does not have any docs.
> 
> http://dpldocs.info/locate/?searchTerm=std.windows.registry
> 
> 
> This is one of the big reasons why I decided *against* using dmd for my doc generation thing - it actually follows `version` rules which is necessary for compiling, but a bad thing for docs! So instead I did a separate parser.
> 
> Join me and together we rule the Dalaxy with good documentation!

Maybe we should *replace* the current docs with dpldocs... Make dpldocs the official doc system. Throw out the current half-baked stuff...


T

-- 
Without outlines, life would be pointless.