On Friday, 23 January 2015 at 10:31:45 UTC, aldanor wrote:
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).
i think it'd be great if you and sebastiaan koppe worked
together. you guys can get together and combine your efforts so
one of the work would not go in vain.