dlang.org redesign -- general thoughts and issues [part 1]

[aldanor via Digitalmars-d]

Hi all, I've started redesigning dlang.org AGAIN (yea, I 
know...). The front page is mostly done aside from a several 
responsiveness and platform quirks, I will have the full landing 
page + a random sample page from the docs this weekend. On the 
technical side, rapid design + ddoc and working with pure css 
don't work well together, so it's going to be a static page or 
two and if/when everyone/anyone's happy with it, it can be pulled 
apart into those fugly ddoc macros. An easy example of why that's 
the case would be changing the color scheme or general styling of 
multiple components -- in sass/less you can just do a 
"@active-component: darken(@martian-red, 5%);" and that will fix 
all the inherited ones across the stylesheet. Same applies to 
reorganizing content in drastic ways. If using node as a 
dependency to compile assets is acceptable, this would sure the 
preferred way; otherwise, the compiled assets could be 
frozen/minified and checked back in. More about design-specific 
stuff later in another post.

There are several issues with structure and presentation that I 
think will have to be addressed. While compiling these, I also 
had several people that know nothing about D look at the website 
structrure and make independent comments. Please see my 
semi-organized collection of thoughts below.

Top-level link: APPENDICES

... what is that even supposed to mean? It looks more of an 
official D style guide. TODO: rename to D STYLE GUIDE. TODO: 
someone needs to go through it and update it to look more 
official-style-guide-ish. And then again, it may be moved into a 
learning/docs section and not be a top-level item.

Top-level link: FAQ

... looks like a collection of stuff that doesn't belong 
anywhere. The "FAQ" is almost as bad as naming it "MISC". Some of 
the points actually look like they belong to an FAQ ("why D?"), 
other ones belong to an official guide or examples; I wouldn't 
ever guess that the info on anonymous structs/unions would be in 
FAQ, that's just wrong. (there's also Books & Articles --> 
How-tos etc; which makes it even harder).

Top-level link: D1 HOME

... should be buried away somewhere deep as not to scare people 
away. Those who need to find it already know where it is.

Top-level-link: CHANGELOG

... is stale and rarely / randomly updated. This makes it look 
like there is no development on the backend/phobos/runtime going 
on whatsoever. There either needs to be an automated aggregator 
for github pull requests (in which case there will need to be a 
better policy on commit/pr descriptions so it's automatable), or 
a responsibility of whoever's merging it to spend 5 seconds of 
time to update the changelog (e.g. nasty ice bug fixed, bugzilla 
issue #123, github pr #456).

There should also be a friendly way to quickly see a list of 
releases with dates and summaries and navigate to release notes 
for each one without scrolling through 42km of text.

Top-level link: SITEMAP

... should be removed, it's not 1999 anymore. Plus, a 
well-structured website never needs a sitemap.

Top-level-link: VISUAL D

... should move under Downloads & Tools; having this at top-level 
has a Windows smell and may scare people away.

Top-level links: STANDARD LIBRARY, D REFERENCE

... I suggest they are moved back into Documentation section (as 
it is on the forum.dlang.org) which will contain these (Language 
Reference / Standard Library) plus other subsections e.g. D Style 
Guide.

Book->Tutorial link (on forum.dlang.org) and other external links:

This is one of many random external links: 
http://www.informit.com/articles/article.aspx?p=1381876. It's 
just a really bad style for an official language website to link 
to an article obscure external website (that is 5 years old and 
probably outdated anyway). I suggest this is removed; and, in 
case any of the information in that tutorial is not duplicated in 
other guides, be manually moved/copied somewhere else (or be made 
a part of the official guide/tutorial).

REVIEW QUEUE:

... has this even changed at all in 6 months? If not, remove it 
from top-level. This gives an impression of stagnation if anyone 
were to follow that link and click "History" (I did).