On Tuesday, 18 February 2020 at 20:50:19 UTC, H. S. Teoh wrote:
> 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

I frankly much prefer the current docs over dpldocs. While dpldocs
might be technically superior, the UI is quite bad, it looks cold and
cluttered to me. A large part of this can probably be fixed through CSS
changes, though.

On Wednesday, 19 February 2020 at 11:15:33 UTC, Les De Ridder wrote:
> On Tuesday, 18 February 2020 at 20:50:19 UTC, H. S. Teoh wrote:
>> On Tue, Feb 18, 2020 at 07:08:56PM +0000, Adam D. Ruppe via Digitalmars-d wrote:
>>> [...]
>>
>> Maybe we should *replace* the current docs with dpldocs... Make dpldocs the official doc system. Throw out the current half-baked stuff...
>>
>>
>> T
>
> I frankly much prefer the current docs over dpldocs. While dpldocs
> might be technically superior, the UI is quite bad, it looks cold and
> cluttered to me. A large part of this can probably be fixed through CSS
> changes, though.

+1 ...

On Wednesday, 19 February 2020 at 11:15:33 UTC, Les De Ridder wrote:
> On Tuesday, 18 February 2020 at 20:50:19 UTC, H. S. Teoh wrote:
>> 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
>
> I frankly much prefer the current docs over dpldocs. While dpldocs
> might be technically superior, the UI is quite bad, it looks cold and
> cluttered to me. A large part of this can probably be fixed through CSS
> changes, though.

I agree. It's not a problem for me, but if it's the *official* documentation generator, it needs a better design. That shouldn't take much though. These days there are tons of static site generators, so it's easy to steal a design.

On Wednesday, 19 February 2020 at 11:15:33 UTC, Les De Ridder wrote:
> A large part of this can probably be fixed through CSS changes, though.

If you send me a concept sketch or css suggestion we can talk about it.

I have a somewhat long list of things that I'm not happy with, though any fix for those needs to not break the things that do work... and the problem I've had isn't so much identifying the problems as finding the solutions.

So I'd prefer specific fix ideas over general "I don't like this" things.

On Wednesday, 19 February 2020 at 16:37:41 UTC, Adam D. Ruppe wrote:
> On Wednesday, 19 February 2020 at 11:15:33 UTC, Les De Ridder wrote:
>> A large part of this can probably be fixed through CSS changes, though.
>
> If you send me a concept sketch or css suggestion we can talk about it.
>
> I have a somewhat long list of things that I'm not happy with, though any fix for those needs to not break the things that do work... and the problem I've had isn't so much identifying the problems as finding the solutions.
>
> So I'd prefer specific fix ideas over general "I don't like this" things.

If it's going to become the official documentation, it needs to match the existing website 100%. That's not currently the case.

The other thing that immediately stands out to me when I click a random project's documentation, like this:
https://hunt-database.dpldocs.info/hunt.html
is that the page doesn't contain a lot of information. This
https://dlang.org/phobos/std_range.html
is much more approachable. Maybe that can be avoided, I don't know, but the first example doesn't bring me joy.

I'm not the biggest fan of all the information on this page (comparing apples to apples now):
http://dpldocs.info/experimental-docs/std.range.html
I think it would be better to be able to click to expand if you want information about types. iota, for instance, is cluttered but the extra information doesn't bring much to the table.

I also don't understand why the functions are listed twice.

On Wednesday, 19 February 2020 at 17:09:02 UTC, bachmeier wrote:
> The other thing that immediately stands out to me when I click a random project's documentation, like this:
> https://hunt-database.dpldocs.info/hunt.html
> is that the page doesn't contain a lot of information.

That's because the author of that project wrote near-zero documentation. I can't fix that myself.

> I think it would be better to be able to click to expand if you want information about types. iota, for instance, is cluttered but the extra information doesn't bring much to the table.

Yeah, the members list is one of the things I'm not really happy with.

I'm not sure there's any real value in separating out classes, structs, enums, etc., and I do think it shows too much there.

I did just fix a bug in it so it doesn't duplicate those function prototypes (actually the technical difference was they had separate constraints, but sine that isn't visible here it looked like a total duplicate and waste) anymore.

But the other worry is the information on the right. Part of this is that the documentation in the source doesn't really follow the spec. https://dlang.org/spec/ddoc.html#summary says the first thing in a ddoc comment is supposed to be a short summary. Then you put in a paragraph break and write the rest of your details.

Though maybe I can just limit the size on my side though.

But yeah this members list is one of the things I was never actually happy with so I'm open to any ideas to change it, potentially up to a total replacement.

if you refresh this now you can see some changes:
http://dpldocs.info/experimental-docs/std.range.html


> I also don't understand why the functions are listed twice.

Ddoc's limitations led to the authors writing it out by hand, but then my  generator auto-generates a list and doesn't realize the hand-written list is there (and even if it did, the hand written list is frequently incomplete!).

So now it has both.

The ddox version on the official site does basically the same thing for the same reason:

 https://dlang.org/library/std/range.html

ddox strips types out of its listing on the left, something I've also considered, but I find types to be really useful...


My generator also has the ability to group functions into categories

http://dpldocs.info/experimental-docs/arsd.nanovega.html#members

but that requires a tag be added to the source and Phobos does the hand-written tables instead of tags on the functions since ddoc doesn't support tagging anyway. so bleh.

On Wednesday, 19 February 2020 at 16:37:41 UTC, Adam D. Ruppe wrote:
> On Wednesday, 19 February 2020 at 11:15:33 UTC, Les De Ridder wrote:
>> A large part of this can probably be fixed through CSS changes, though.
>
> [...]
>
> So I'd prefer specific fix ideas over general "I don't like this" things.

I don't particularly feel like bikeshedding too much about what it
should look like, I'm not great at UI design. That said, I think the
design of the current official docs is pretty good and fits in well with
the rest of dlang.org.

Some of the things that I think would help: add more padding, simplify
the colour scheme, use monospaced fonts, use less bold fonts.

Examples after fiddling around with the CSS for a couple minutes:

Before: https://u.sicp.me/m2sMw.png
After: https://u.sicp.me/ieJht.png
Official docs: https://u.sicp.me/kzZTg.png

(Maybe we ought to move this to a seperate thread or to IRC/Slack?)

On Thursday, 20 February 2020 at 00:11:58 UTC, Les De Ridder wrote:
> On Wednesday, 19 February 2020 at 16:37:41 UTC, Adam D. Ruppe wrote:
>> On Wednesday, 19 February 2020 at 11:15:33 UTC, Les De Ridder wrote:

Guys, can we please keep this thread focused on specific documentation issues like I asked? I want as many issues as we can get and to be able to go through the thread without wading through lots of off topic discussion.

Thanks!

On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
> Preliminary discussions are underway for a new event to encourage improvements to documentation across the D ecosystem. I can't provide any details yet because the details aren't yet fixed. I don't even know for sure it's going to happen.
>
> However, the best way to make it happen is for us to have a solid set of well-defined documentation tasks. Putting that together is going to require help from the community. All of us have encountered areas where improvement is needed in the spec, the Phobos docs, and docs for dub, vibe.d, and many other tools and projects around the D ecosystem. Some of it has made it into Bugzilla (which will be mined for material), but much of it has been buried in the forum archives or evaporated into the ether from the IRC/Discord/Slack channels.
>
> 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.
>
> Any project in the D ecosystem is fair game. So please help us out and tell us how D documentation can be improved for you.
>
> 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!

1. Dub documentation

DUB needs much, much better documentation. Especially cookbooks (there's already some, but it is not accessible enough IMO). Example of how to structure a project (writing a library with an executable, writing a project with examples that are separate and compile, writing a client/server app or any two apps linked together, writing a project that interface with C/C++, writing a project that use some preprocessor, e.g. dtoh, etc..).

Some of this documentation will *also* require fixes to Dub (e.g. https://github.com/dlang/dub/issues/1474 for anything using preprocessor). There is a feature that allows a project to provide skeleton for apps using it, it might also be useful to try to do it with a few projects.

2. DMD documentation

Inexistent. Enough said.

3. C++ interfacing documentation

The documentation for interfacing with C++ is ridiculously outdated (e.g. it says that operators overloads are not callable from D). I am currently rewriting it.

Also, some other features are not documented. It would be helpful to have a language expert going over it and see what missing (e.g. yesterday I found out `pragma(crt_{con,de}structor)` was missing, despite being in the language since 2018-01-01). But I don't have specific example of missing features ATM.

4. Documentation history

https://issues.dlang.org/show_bug.cgi?id=20588

5. More pattern documentation

Some of https://github.com/zhaopuming/awesome-d could be integrated in the website, e.g. I've never heard of https://garden.dlang.io/ before!
Likewise, http://p0nce.github.io/d-idioms/ provide amazing tips. One (anecdotal) example is that `enum` is over-used in the docs while `static immutable` (with initializer) should arguably be the default for people.

On Wednesday, 19 February 2020 at 16:37:41 UTC, Adam D. Ruppe wrote:
> On Wednesday, 19 February 2020 at 11:15:33 UTC, Les De Ridder wrote:
>> A large part of this can probably be fixed through CSS changes, though.
>
> If you send me a concept sketch or css suggestion we can talk about it.
>
> I have a somewhat long list of things that I'm not happy with, though any fix for those needs to not break the things that do work... and the problem I've had isn't so much identifying the problems as finding the solutions.
>
> So I'd prefer specific fix ideas over general "I don't like this" things.

My general problem with most docs is that I actually prefer the "one big page" approach per-module. The practical relationships between functions, objects, methods and members often aren't hierarchical and it's so much easier to get an overview by scrolling through a larger page.

The same reason applies to why I almost never use code-folding in an editor.