On Wednesday, 19 February 2020 at 20:47:11 UTC, Adam D. Ruppe wrote:

> 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.

That's pretty cool

On Thursday, 20 February 2020 at 03:32:50 UTC, Mathias Lang wrote:
> On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
>> [...]
> 1. Dub documentation
>
> I agree.
>
> 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
>
> I agree. Not only code documentation but also overview & c. It's very difficult to help with dmd development starting from nothing.


I would add a thing. Consider this:

bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2)
if (isInputRange!Range1 && isInputRange!Range2 && !isInfinite!Range1 && !isInfinite!Range2);

It's a pretty easy example of a function template. But I guess it is quite confusing for a newcomer. Why do we need to focus documentation on function signature? Can't we replace the function signature as main piece of information with something more easier to read for a newcomer?





Andrea

On Thu, Feb 20, 2020 at 10:21:25AM +0000, John Colvin via Digitalmars-d wrote: [...]
> 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.

Yeah, the one-page doc is nicer because you can actually search for keywords on the page and find what you want, instead of having to click on who knows how many links just to get to the one place you already know is there.


T

-- 
Marketing: the art of convincing people to pay for what they didn't need before which you fail to deliver after.

On Friday, 21 February 2020 at 19:27:51 UTC, H. S. Teoh wrote:
> Yeah, the one-page doc is nicer because you can actually search for keywords on the page and find what you want, instead of having to click on who knows how many links just to get to the one place you already know is there.

But on the other hand, external search engines do a very poor job actually getting you there.

That's why my site does a bit of both: dpldocs.info/std.ascii will search for you, the module page has an overview listing of members, and you have clear URLs for outside linking.

Even on the current dlang.org site, the ddox versions are more likely to pop up on outside web searches than the ddoc single page one!

https://abload.de/img/tmpenki4.png - web 2.0 went too far.

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.

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'm about to publish a blog post announcing this (a few minutes after I hit 'Send' on this post):

We need documentation of strategies to optimize your code to get the best performance. There are numerous hacks that people suggest - look at this example

https://forum.dlang.org/post/ezomjijivexzrwtbtahn@forum.dlang.org

but we should be able to link to a guide. Related to this, we need documentation on strategies to write programs without the GC.

On Monday, 2 March 2020 at 14:13:16 UTC, p.shkadzko wrote:
> [snip]
>
> 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.

I agree that there could be some improvement here. I've intended to write something up, but haven't. There is a blog post from Shigeki Karita that is listed in the readme.md that I recall doing a decent job, but it is in Japanese and Google Translate doesn't seem to run on it anymore. I think there is an issue with the certificate or something. Probably just making a English version of it more easily available would be a step in the right direction.

On Monday, 2 March 2020 at 16:55:36 UTC, jmh530 wrote:
> On Monday, 2 March 2020 at 14:13:16 UTC, p.shkadzko wrote:
>> [...]
>
> I agree that there could be some improvement here. I've intended to write something up, but haven't. There is a blog post from Shigeki Karita that is listed in the readme.md that I recall doing a decent job, but it is in Japanese and Google Translate doesn't seem to run on it anymore. I think there is an issue with the certificate or something. Probably just making a English version of it more easily available would be a step in the right direction.

I'd love to help and write some docs. Maybe something like a simplistic tutorial that Numpy has would already be great.

On Tuesday, 3 March 2020 at 15:30:40 UTC, p.shkadzko wrote:
> [snip]
>
> I'd love to help and write some docs. Maybe something like a simplistic tutorial that Numpy has would already be great.

If you need someone to review it, I'd be happy to.