www.digitalmars.com         C & C++   DMDScript  

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

reply "aldanor" <i.s.smirnov gmail.com> writes:
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 


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).
Jan 23 2015
next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2015-01-23 11:31, 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.


For Sass there's libsass [1] with bindings already available [2]. For 
running JavaScript (Less) there are a couple of alternatives:

* Google V8
* Mozilla Rhino
* Apple JavaScriptCore - Included with Mac OS X
* Microsoft Windows Script Host (JScript)
* DMDScript [3]

In the Ruby world there's a gem that automatically chooses the best 
scripting host depending on the platform.

[1] http://libsass.org
[2] http://forum.dlang.org/thread/hdbsilimsxzhlruthign forum.dlang.org
[3] http://code.dlang.org/packages/dmdscript

-- 
/Jacob Carlborg
Jan 23 2015
parent "aldanor" <i.s.smirnov gmail.com> writes:
On Friday, 23 January 2015 at 12:32:00 UTC, Jacob Carlborg wrote:

 For Sass there's libsass [1] with bindings already available 
 [2]. For running JavaScript (Less) there are a couple of 
 alternatives:


Thanks, that would help. Could either use bootstrap-sass from git 
+ d bindings to libsass from dub, or alternatively less via 
dmdscript -- but the first one would be easier, I guess.
Jan 23 2015
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2015-01-23 11:31, aldanor wrote:


 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



It's updated when there's a new release.


 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.


I think they deserve being top-level links.


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


Probably not. Nothing has happened in the review queue for quite a while.

-- 
/Jacob Carlborg
Jan 23 2015
parent "aldanor" <i.s.smirnov gmail.com> writes:
On Friday, 23 January 2015 at 12:47:36 UTC, Jacob Carlborg wrote:

 Top-level-link: CHANGELOG


 It's updated when there's a new release.


Not always -- e.g. there's several notes on 2.067 there already. 
I always thought that updating the changelog right after you fix 
something is easier than trying to recall whatever it was the 
hell you were working on half a year later and/or recover it from 
commits and pull requests, but to each his own, I guess. Plus, 
the changelog will have to be there anyway before the release so 
it's unavoidable. The question is whether it should be updated 
more frequently or in a more organized fashion. It's good 
publicity and it's nice to have a "sneak peek" of the next 
release to keep people excited, all I'm saying.

On Friday, 23 January 2015 at 12:47:36 UTC, Jacob Carlborg wrote:

 Top-level links: STANDARD LIBRARY, D REFERENCE


 I think they deserve being top-level links.


I'd argue that the top links should be "Learn" (official D 
newcomer's guide which is not written yet, more about it on my 
next post / "D by example" which is not written yet either / 
gotchas and faqs / porting c/c++ / books and articles) and "Docs" 
(which would be: standard library / language reference / official 
style guide). These two are intertwined and scattered all over 
the place on D website. Examples: http://ocaml.org/ ("Learn" / 
"Documentation"),  http://www.rust-lang.org/ ("Book" / 
"Reference"), etc. This would be much more newbie-friendly. For D 
veterans, we could just add shortcuts to quickly jumping to 
stdlib or language reference.
Jan 23 2015
prev sibling next sibling parent "Mengu" <mengukagan gmail.com> writes:
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 


 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.
Jan 23 2015
prev sibling next sibling parent reply "Christof Schardt" <Christof Schardt.info> writes:
"aldanor" <i.s.smirnov gmail.com> schrieb im Newsbeitrag 
news:didzczqdggjchqgtgvti forum.dlang.org...

 Hi all, I've started redesigning dlang.org AGAIN (yea, I


Very sensible considerations. I think your way is the right
way to go: first think about structure, then presentation
and finally style.
Jan 23 2015
parent reply "Chris" <wendlec tcd.ie> writes:
On Friday, 23 January 2015 at 13:39:23 UTC, Christof Schardt 
wrote:

 "aldanor" <i.s.smirnov gmail.com> schrieb im Newsbeitrag 
 news:didzczqdggjchqgtgvti forum.dlang.org...

 Hi all, I've started redesigning dlang.org AGAIN (yea, I


 Very sensible considerations. I think your way is the right
 way to go: first think about structure, then presentation
 and finally style.


Yep. And please: accessibility. We wouldn't want to put off 
visually impaired users. JS gives them pain.
Jan 23 2015
parent reply "aldanor" <i.s.smirnov gmail.com> writes:
On Friday, 23 January 2015 at 19:18:34 UTC, Chris wrote:

 On Friday, 23 January 2015 at 13:39:23 UTC, Christof Schardt 
 wrote:

 "aldanor" <i.s.smirnov gmail.com> schrieb im Newsbeitrag 
 news:didzczqdggjchqgtgvti forum.dlang.org...

 Hi all, I've started redesigning dlang.org AGAIN (yea, I


 Very sensible considerations. I think your way is the right
 way to go: first think about structure, then presentation
 and finally style.


 Yep. And please: accessibility. We wouldn't want to put off 
 visually impaired users. JS gives them pain.


Yep, that crossed my mind as well, good point. You sort of get
that for free when using mature css frameworks since all elements
are already ridden with things like 'role="navigation"' etc :)
Jan 23 2015
parent "Orvid King" <blah38621 gmail.com> writes:
On Friday, 23 January 2015 at 19:20:11 UTC, aldanor wrote:

 On Friday, 23 January 2015 at 19:18:34 UTC, Chris wrote:

 On Friday, 23 January 2015 at 13:39:23 UTC, Christof Schardt 
 wrote:

 "aldanor" <i.s.smirnov gmail.com> schrieb im Newsbeitrag 
 news:didzczqdggjchqgtgvti forum.dlang.org...

 Hi all, I've started redesigning dlang.org AGAIN (yea, I


 Very sensible considerations. I think your way is the right
 way to go: first think about structure, then presentation
 and finally style.


 Yep. And please: accessibility. We wouldn't want to put off 
 visually impaired users. JS gives them pain.


 Yep, that crossed my mind as well, good point. You sort of get
 that for free when using mature css frameworks since all 
 elements
 are already ridden with things like 'role="navigation"' etc :)



Although I like the new look overall, there are a few things on 
the docs for the standard library that aren't the best they could 
be.

Currently a jump-to list is generated for all elements with 
children, regardless of the number of them. I believe that no 
jump list (apart from the one to navigate the entire page) should 
be shown if there are 2 items or less, because the user can 
already see the entire content that would be linked to.

Now on to the positioning of the jump links themselves. Currently 
they are positioned above the declaration of the element who's 
children it jumps to. I believe that the jump links should 
instead be in the body of the element, after the description, but 
immediately before any children.

Children with overloads 

don't currently merge like the they do at the top-most level.

Enums should probably be formatted differently from normal types, 
with a table of it's members rather than a list, as enum member 
descriptions tend to be more minimal. Parhaps use a table-view 
when there is only one line for the description of every member 
of the enum, and the current list view otherwise?
Jan 23 2015
prev sibling next sibling parent reply "Zach the Mystic" <reachzach gggmail.com> writes:
On Friday, 23 January 2015 at 10:31:45 UTC, aldanor wrote:

 Hi all, I've started redesigning dlang.org AGAIN (yea, I 
 know...).

 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.


My own thought:

http://forum.dlang.org/post/pywtsfqqrqigxynfakdx forum.dlang.org

Basically, I suggest consciously addressing these four 
demographics in designing the site:

1. Experienced programmers, new to D.

2. Beginning programmers.

3. Experienced D users.

4. The community. Publications, social events, news chatter.
Jan 23 2015
parent "aldanor" <i.s.smirnov gmail.com> writes:
On Friday, 23 January 2015 at 17:41:21 UTC, Zach the Mystic wrote:

 Basically, I suggest consciously addressing these four 
 demographics in designing the site:

 1. Experienced programmers, new to D.

 2. Beginning programmers.

 3. Experienced D users.

 4. The community. Publications, social events, news chatter.


Agreed.


points will need to be addressed). E.g., Ali's book is more aimed 

has to be a "I know how to code, give me some D already, now!" 
sort of a brief guide which would introduce you to the COOL parts 
that are different in D or that make it stand out. An experienced 
programmer could just jump into metaprogramming part right away 
because it's FUN... but that usually doesn't come until page 500 
of the book...


subjective opinion because everyone's used to how things are, but 
here goes anyway: (1) mailing lists are too 90s, there exist many 
modern platforms that are better suitable for modern web and 
mobile, the current forum is actually a heroic attempt to make 
something usable out of a mailing list but that's that. No syntax 
highlighting, no editing? Come on... (2) bugzilla is too 
unfriendly; using github issues for review queues, milestone 
tracking, bug tracking, issue tracking and referencing would be 
easier than scattering all that across 4 different websites (that 
aren't updated anyway). I have found a good amount of bugs in my 
D experience but I'm guilty of not submitting a single one 
because I don't feel like making an account on bugzilla -- and 
I'm not planning too, it instantly repulses me as soon as I open 
the page; plus it's unintuitive to browse, contains outdated 
issues and just feels foreign in general.
Jan 23 2015
prev sibling parent "Laeeth Isharc" <laeethnospam nospam.laeeth.com> writes:
 Hi all, I've started redesigning dlang.org AGAIN (yea, I 
 know...).


Appreciate the work you and others are doing on this.  Web pages 
are so fiddly but so important for controlling the image one 
presents to the world.

I don't have so much to say about the general case, as it is not 
my field.  But a couple of thoughts in relation to the content 
generally.

About/History.  A link on the front page to a few paragraphs 
setting the context for how D came about might be good.  It's a 
very powerful story of how Walter came to write D, and Andrei's 
subsequent involvement.  You could replace the Acknowledgements 
section by this, and place this underneath the story with also a 
bit more colour on who the other major contributors are - some 
short bios.

Why D?.  It's the first question people will want answered when 
coming to the site, and they have to dig around quite a lot to 
get the complete picture.

FAQ - since the FUD crowd keep bringing it up (see Slashdot 
discussion of D lang), perhaps the tango vs phobos and D1 vs D2 
questions should be answered within the FAQ.  Also the "DMD is 
not open source" canard.

"> Top-level link: SITEMAP ... should be removed, it's not 1999 
anymore. Plus, a

 well-structured website never needs a sitemap".


Honestly, I am not so sure that is right.  In the age of the iPad 
and Kindle, books still have indexes, and they are very useful on 
occasion, and I think this does apply to websites too, whatever 
the fashion to day may be.  If you know what you are looking for 
then good structure helps, but one doesn't always know what one 
is looking for.


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


Perhaps that is right.  However if so, under Downloads and Tools 
there needs to be a little bit of introduction and context rather 
than bam DMD2.066.1.  If I have just arrived knowing nothing 
about D and want to get started, what is DMD???  And GDC, LDC.  
Which one do I pick?

Dashing something off quickly:

"There are three mature compilers for the D programming language.

1. DMD is the reference implementation originated and maintained 
by Walter Bright, and available for Linux, Free BSD, and OS X.  
Android/x86 support is mature but not yet fully complete, whilst 
Android/ARM is currently at a pre-alpha stage.[Link 
http://wiki.dlang.org/Build_DMD_for_Android]

DMD is known for its exceptionally fast compilation times - for 
example, the standard library, Phobos, takes only XX minutes to 
compile on a standard Amazon m1.medium image.  This brings the 
benefits of scripting languages such as Python for enabling rapid 
iterative development; it allows D to be used as a scripting 
language [link to RDMD] and permits the creation of dynamically 
compiled extensions to running programs - see DREPL [link] for an 
example.

The compiler is free to use, the full source code is supplied 
with the compiler, and the front end is fully open source under 
the Boost(?) license.  Although the back end is licensed from 
Symantec and this is not compatible with GPL-style licenses, all 
development takes place publicly on github.  [Say briefly what 
can and can't be done under the license and link to the FAQ for 
fuller explanation of the licensing].

2. GDC is a fully open-source compiler that uses the Gnu GCC 
back-end to generate native code and for some applications may 
generate faster, more optimized code than DMD.  It is available 
for Intel architecture Linux, ARM architecture Linux, and 
Windows.  Android support is under development and not yet fully 
mature [http://wiki.dlang.org/GDC/Installation/Android]

3. LDC is a fully open-source compiler that uses the LLVM 
back-end to generate native code and for some applications may 
generate faster, more optimized code than DMD.  It is available 
for ...

The DMD section should have a link to installation instructions 
as well as how to resolve commonly experienced problems.

The download page should also have a section for IDEs and 
debuggers.  Not just Visual D.  I suggest it should also have a 
link to dstep github page and direct link to download binaries 
for each platform (they are tucked away in a subdirectory).

Library interoperability is a key barrier to adoption of D, and 
when you arrive at the website, it is not obvious immediately how 
to do this.  Maybe on front page there should be a top-level 
section "Interoperability" or some more mellifluous title linking 
to a piece saying the following

"D fully supports the C application binary interface (ABI), which 
means that D programs can link to C object files and libraries 
and achieve full interoperability.  The only step required is to 
translate C .h header files to D format, and this can be done 
automatically using the dstep tool (available here[link]) or on 
Windows using the htod tool (available here[link]).

Substantial C++ interoperability exists, but this is an area 
under development and is a priority for the D language for 2015.  
Documentation on linking to C++ is here[link], and Calypos is an 
alpha project to achieve full interoperability with the LDC 
compiler.  [link].




 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.


Shouldn't the most frequently accessed links be available from 
one click from the main page?  If it's just under a dynamic 
sub-menu, thats fine though.
Jan 23 2015