Re: dlang.org redesign -- general thoughts and issues [part 1]
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/pywtsfqqrqigxynfa...@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.
Re: dlang.org redesign -- general thoughts and issues [part 1]
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.
Re: dlang.org redesign -- general thoughts and issues [part 1]
On Friday, 23 January 2015 at 13:39:23 UTC, Christof Schardt wrote: aldanor i.s.smir...@gmail.com schrieb im Newsbeitrag news:didzczqdggjchqgtg...@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.
Re: dlang.org redesign -- general thoughts and issues [part 1]
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.smir...@gmail.com schrieb im Newsbeitrag news:didzczqdggjchqgtg...@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 :)
Re: dlang.org redesign -- general thoughts and issues [part 1]
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.smir...@gmail.com schrieb im Newsbeitrag news:didzczqdggjchqgtg...@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?
Re: dlang.org redesign -- general thoughts and issues [part 1]
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.
Re: dlang.org redesign -- general thoughts and issues [part 1]
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.
Re: dlang.org redesign -- general thoughts and issues [part 1]
aldanor i.s.smir...@gmail.com schrieb im Newsbeitrag news:didzczqdggjchqgtg...@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.
Re: dlang.org redesign -- general thoughts and issues [part 1]
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
dlang.org redesign -- general thoughts and issues [part 1]
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).
Re: dlang.org redesign -- general thoughts and issues [part 1]
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/hdbsilimsxzhlruth...@forum.dlang.org [3] http://code.dlang.org/packages/dmdscript -- /Jacob Carlborg
Re: dlang.org redesign -- general thoughts and issues [part 1]
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
Re: dlang.org redesign -- general thoughts and issues [part 1]
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.
