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