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.

Any news here?

On Saturday, 2 May 2020 at 18:02:11 UTC, Panke wrote:
> 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.
>
> Any news here?

Not yet. It's going to happen at some point if we can sort out enough concrete documentation tasks.

On Sunday, 3 May 2020 at 01:37:54 UTC, Mike Parker wrote:
> Not yet. It's going to happen at some point if we can sort out enough concrete documentation tasks.

Insight from a D newcomer for easier Dlang accessibility. Not everything is documentation per se:

- promote wiki.dlang.org directly on D's webpage

- promote authors to copy/write/(at least link) articles/tutorials/cookbooks on the wiki (there are many, but also many are scattered threw out the web)

- copy Dlang's blog to wiki (keep the blog, but collect information in one place. Plus points if directly sorted what the blog post was: article/tutorial/cookbook)

- declare unmaintained packages as such (once a month I read the question, whether derelict works, and once a month Mike answers, that he does not maintain it anymore. And this goes on for many packages. In addition it is hard to a newcomer to see, whether a package is abandoned, or finished. Example: coming from python word, anything which didn't have a commit in last 2 years is fishy)
( I don't want to attack you Mike, it is just an example, but since you are the one I am answering right now, it is the example)

- decrease score of packages, which don't build on code.dlang.org

- Language and library reference have enough examples (at least the parts I use). Examples are simple and clear. However to a newcomer needs also more complex examples, like tutorials or cookbooks. Idea: one link, on the specific reference to a section with related articles/tutorials/cookbooks.

- opinionated suggestions in getting started https://wiki.dlang.org/Getting_Started (a newcomer is overwhelmed by the possibilities of compilers,editors/ides. Suggestions: dmd, vscodium with code-d)

- probably pack this task list somewhere on the wiki

- Encourage newcomers to edit the wiki. This is a simple task, often dull to do for experienced community members, but great for newcomers, because they are included AND they explore the wiki ant the community on themselves.

On Sunday, 3 May 2020 at 07:35:03 UTC, Jan Hönig wrote:
> - Encourage newcomers to edit the wiki. This is a simple task, often dull to do for experienced community members, but great for newcomers, because they are included AND they explore the wiki ant the community on themselves.

I felt encouraged today, so I created this list[1]
I hope it was OK.

Please feel free to fill, sort & enhance.


[1]: https://wiki.dlang.org/Documentation_improvement_initiative

On Tuesday, 5 May 2020 at 16:05:44 UTC, Jan Hönig wrote:
> On Sunday, 3 May 2020 at 07:35:03 UTC, Jan Hönig wrote:
>> - Encourage newcomers to edit the wiki. This is a simple task, often dull to do for experienced community members, but great for newcomers, because they are included AND they explore the wiki ant the community on themselves.
>
> I felt encouraged today, so I created this list[1]
> I hope it was OK.
>
> Please feel free to fill, sort & enhance.
>
>
> [1]: https://wiki.dlang.org/Documentation_improvement_initiative

Thanks!

I'm still looking for documentation tasks that require enough work that we can use them for the event. Adding one or two lines here or there isn't enough. And something that requires weeks is too much. We're looking for things that can be accomplished in terms of hours or days.

On Wednesday, 6 May 2020 at 02:34:33 UTC, Mike Parker wrote:
> On Tuesday, 5 May 2020 at 16:05:44 UTC, Jan Hönig wrote:
>> On Sunday, 3 May 2020 at 07:35:03 UTC, Jan Hönig wrote:
>>> - Encourage newcomers to edit the wiki. This is a simple task, often dull to do for experienced community members, but great for newcomers, because they are included AND they explore the wiki ant the community on themselves.
>>
>> I felt encouraged today, so I created this list[1]
>> I hope it was OK.
>>
>> Please feel free to fill, sort & enhance.
>>
>>
>> [1]: https://wiki.dlang.org/Documentation_improvement_initiative
>
> Thanks!
>
> I'm still looking for documentation tasks that require enough work that we can use them for the event. Adding one or two lines here or there isn't enough. And something that requires weeks is too much. We're looking for things that can be accomplished in terms of hours or days.

How about also cleaning up documentation how it looks on the web? Like missing macros are rendered blank in ddox, so the usage or the definition could get fixed. Example missing something: https://vibed.org/api/vibe.db.mongo.mongo/ (ending with "a dedicated utility for this called .", missing the $(LINK2 ...) macro)

ddox also doesn't support showing mixin templates yet, which are however already reported in the JSON by the dmd documentation generator thing and only need some implementation.

Also something I'm finding essential and think should be added to the DDoc spec: $(LREF) and $(REF) - they are used a lot in phobos and (a bit biased) they are also implemented in the code-d doc preview / code tips already for all packages, making them look nicely already there. Even if it just suggests that these are subject to implementation for each documentation generator, having a well defined syntax and explanation would help a lot.

On Wednesday, 6 May 2020 at 05:25:59 UTC, WebFreak001 wrote:
> How about also cleaning up documentation how it looks on the web? Like missing macros are rendered blank in ddox, so the usage or the definition could get fixed. Example missing something: https://vibed.org/api/vibe.db.mongo.mongo/ (ending with "a dedicated utility for this called .", missing the $(LINK2 ...) macro)
>
> ddox also doesn't support showing mixin templates yet, which are however already reported in the JSON by the dmd documentation generator thing and only need some implementation.
>
> Also something I'm finding essential and think should be added to the DDoc spec: $(LREF) and $(REF) - they are used a lot in phobos and (a bit biased) they are also implemented in the code-d doc preview / code tips already for all packages, making them look nicely already there. Even if it just suggests that these are subject to implementation for each documentation generator, having a well defined syntax and explanation would help a lot.

Please add it to the wiki.
https://wiki.dlang.org/Documentation_improvement_initiative#The_List

On 5/5/20 10:25 PM, WebFreak001 wrote:
> On Wednesday, 6 May 2020 at 02:34:33 UTC, Mike Parker wrote:
>> On Tuesday, 5 May 2020 at 16:05:44 UTC, Jan Hönig wrote:
>>> On Sunday, 3 May 2020 at 07:35:03 UTC, Jan Hönig wrote:
>>>> - Encourage newcomers to edit the wiki. This is a simple task, often dull to do for experienced community members, but great for newcomers, because they are included AND they explore the wiki ant the community on themselves.
>>>
>>> I felt encouraged today, so I created this list[1]
>>> I hope it was OK.
>>>
>>> Please feel free to fill, sort & enhance.
>>>
>>>
>>> [1]: https://wiki.dlang.org/Documentation_improvement_initiative
>>
>> Thanks!
>>
>> I'm still looking for documentation tasks that require enough work that we can use them for the event. Adding one or two lines here or there isn't enough. And something that requires weeks is too much. We're looking for things that can be accomplished in terms of hours or days.
> 
> How about also cleaning up documentation how it looks on the web? Like missing macros are rendered blank in ddox, so the usage or the definition could get fixed. Example missing something: https://vibed.org/api/vibe.db.mongo.mongo/ (ending with "a dedicated utility for this called .", missing the $(LINK2 ...) macro)
> 
> ddox also doesn't support showing mixin templates yet, which are however already reported in the JSON by the dmd documentation generator thing and only need some implementation.
> 
> Also something I'm finding essential and think should be added to the DDoc spec: $(LREF) and $(REF) - they are used a lot in phobos and (a bit biased) they are also implemented in the code-d doc preview / code tips already for all packages, making them look nicely already there. Even if it just suggests that these are subject to implementation for each documentation generator, having a well defined syntax and explanation would help a lot.

Incidentally in my -preview=markdown changes putting a symbol in brackets (using Markdown syntax for a link) like [string] creates a link to that symbol's definition [1]. I suspect my implementation isn't perfect, but like the rest of the -preview=markdown changes my hope is that it makes the docs easier to write.

[1]: https://dlang.org/spec/ddoc.html#reference_links

On Wednesday, 6 May 2020 at 14:24:53 UTC, David Gileadi wrote:
> Incidentally in my -preview=markdown changes putting a symbol in brackets (using Markdown syntax for a link) like [string] creates a link to that symbol's definition

Yeah, my adrdox does something similar. http://dpldocs.info/experimental-docs/adrdox.syntax.html#cross-referencing

I also rewrite REF and LREF into it for phobos compatibility internally but it is a pretty obvious win to define these.

(actually adrdox defines EVERYTHING and doesn't allow user-defined macros at all. Standardization makes it easier to use here. I just hard-coded the supported ones and leave the rest the unmodified.)

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.


I am exactly such a person today!  The last time I did anything with sockets was 15 (?) years ago, and was very basic, and only for part of one day.

This week, I wanted to toss together a quickie tool to send some test data in binary over UDP to another machine.  I had to forget about the "quickie" part of that.

All the info I need about D and its libraries is there, but often details are hard to find if I don't already know the name of the module to look in. More examples would help. Just basic usage examples, not too basic, but enough to do something simple.

Running off somewhere else to learn UDP sockets in C or Python or whatever then coming back isn't my idea of efficiency.  Would-be users of D coming from science, engineering, fine arts, economics, robotics, or wherever, are likely to be interested in the good features of D but unlikely to want to learn another language to understand some feature, such as sockets.

D documentation shouldn't try to explain these sorts of things from scratch, of course, but a few of the very fundamental ideas need to be shown in an example and a few words.