Documentation Improvement Initiative

[p.shkadzko]

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!

I would really like to see "Mir" library docs get more love: 
http://mir-algorithm.libmir.org

Being a D beginner and coming from Python world I struggle to 
understand why and how some examples work. I lack trivial 
information and for the most part the context. How is mir.ndslice 
`Slice` entity is different from D multidimensional array and why 
is it different in the first place. What is the big purpose and 
goal of the library documentation? When should we prefer it over 
traditional D arrays, etc. etc. This stuff belongs in the 
library. Right now mir docs are dry and incomplete which is a 
shame since it could grow into a serious Numpy alternative and 
bring more people into D.