Improving the D documentation web presentation

WebFreak001 d.forum at webfreak.org
Mon May 25 13:56:10 UTC 2020


as some of you might know, there are 2 versions of the official 
phobos documentation:

ddoc based (https://dlang.org/phobos/index.html)
ddox based (https://dlang.org/library/index.html)

I actually quite like the ddox based documentation for future 
extending because it can contain a lot more information per 
symbol and also allows us to write much larger examples for 
standard library functionality. I think this one has better SEO 
too.

However I still see myself all the time on the ddoc based site as 
it is simply more polished and faster to find multiple symbols in 
a module.

So here I have a few small proposals how we could improve on the 
presentation of the ddox page. I will be referencing to the .NET 
(C#) documentation quite a lot here, because I think it does a 
pretty good job.

Polish the overview: the descriptions of modules are currently 
all kinds of messed up stuff (tables, headings, deprecated 
warnings), having nicer descriptions (only short strings, no 
duplicates, no empty ones) would be a good start for this 
overview page. Also because the left sidebar just shows the same 
as the list of modules, it would probably be smart to remove the 
left sidebar so we have more space for description text. 
Additionally instead of having all APIs in there, I would propose 
to let the user first select the kind of project they are 
interested in (phobos, druntime, dmd) and then only show the 
modules for that project. See 
https://docs.microsoft.com/en-us/dotnet/api/ for an example.

Move the search: the search at the top right is a google search 
on all other D pages. On the ddox it's a quick and easy to use 
search with a different functionality. I think for showing this 
to the user, it should be moved to the left above the module 
tree. This search should also be visible on the index if the 
sidebar is removed there.

Improve navigation: my biggest usability complaint with the ddox 
API pages is that you have to navigate so much to look through 
different symbols inside a module, compared to the ddoc page. 
Much like in the .NET docs, we should show a tree of symbols in 
the sidebar. I think this could nicely fit and also be easier to 
read if we slightly increase the padding per entry, make the 
sidebar scrollable (maybe also add position: sticky) and scroll 
to the currently selected module by default. I think we can also 
improve how the currently active selection looks, because right 
now it is just a darker shade of red with an underline. To not 
overload this with symbols, only symbols in the currently active 
module should be shown as children of a module.

What is your thought on the current ddox and ddoc documentation? 
Which one do you like and/or use more?


More information about the Digitalmars-d mailing list