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 
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).
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
 (e.g. nasty ice bug fixed, bugzilla issue #123, github pr #456).
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 
 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.
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 (http://dlang.org/phobos/std_socket.html#.SocketOSException.this) 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. I personally think #1 is the most troublesome (although all four points will need to be addressed). E.g., Ali's book is more aimed at #2, whereas most other resources are more aimed at #3. There 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... Regarding #4, I don't think anyone would support my highly 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