The core's discuss from dlang-tour

Adapt fonts

In an effort to make it similar to dlang.org ...

Range algorithms example doesn't work online

http://dlang-tour.steinsoft.net/tour/gems/3 runs locally but returns empty result setup when run throught the Docker container.

are markdown tables supported?

Could be quite useful for e.g. the basic types as

type	size	default value
int	32bit	0

send feedback about this page button

Idea from the GoLang tour:

They just use prefill the issue via URL parameters - probably the only thing needed would to make the page url in their dynamic ;-)

https://github.com/stonemaster/dlang-tour/issues/new?title=tour%3A%20%5BREPLACE%20WITH%20SHORT%20DESCRIPTION%5D&body=Context%3A%20https%3A%2F%2Ftour.dlang.org%2Fwelcome%2F5%0A%0AChange%20the%20title%20above%20to%20describe%20your%20issue%20and%20add%20your%20feedback%20here%2C%20including%20code%20if%20necessary

Cache next/previous links

The links to the next and previous section (or chapter) are calculated on each request. This could be cached easily with memoize or something similar from the standard library.

Allow navigation with keyboard controls

As per Mark Isaacson in the D mailing list:

An easy(?) suggestion that would make this easier to browse:
make the left/right arrow keys control advancing to the next
page.

As we don't allow networking or file writes, pretty much anything could be cached. We might of course search for exception (e.g. time if we can't fix this like on the GoTour, see below). The reason for this is obvious, most of the time the user directly click on run without changing the file, so spawning a new docker container and compiling the file just takes unnecessary time.

Btw citing from the GoTour.

In the playground the time begins at 2009-11-10 23:00:00 UTC (determining the significance of this date is an exercise for the reader). This makes it easier to cache programs by giving them deterministic output.

provide dfmt via format

just an idea: automatic code formatting could be quite a help for newbies. For D the tool is called dfmt.

Make everything positioned absolute besides content DIV

Everything should be positioned absolute so that scrolling just scrolls the content and leaves the rest of the layout as it (if it makes sense).

Make Content and source DIVs resizable

The user should be able to resize the source code editor and content DIV to adjust to personal preference.

Possible implementation for AngularJS: https://github.com/Reklino/angular-resizable

Make program output nicer

The program output looks awkward. Its size should be adapted and should fit the rest of the layout.

Use overflow: scroll property accordingly to support scrolling on long outputs.

Add random delay when program output is cached

Instead of directly returning cache contents, add small 500ms-2s delay. This keeps user from suspecting weird stuff.

syntax highlighting for D

for markdown you could use https://highlightjs.org (they support D) (content just needs the "d" class) and you can build a custom package ;-)
codemirror supports D out-of-the-box: http://www.cs.princeton.edu/~dp6/CodeMirror/mode/d/index.html

Store current editor content

When the user changed the source code in the editor the content will be lost as soon as another section is navigated to. The source code editor content should be saved somehow and restored to allow changing source and navigating through the content at the same time.
The Go Tour implements this by having a full stack Angular JS application that keeps the data on the client side. But this means more logic on client side and not on server/vibe.d side.

Hide empty source code editor directly in DIET Template

Instead of using AngularJS to show or hide the source code editor this should be done statically with D syntax of DIET templates. Currently there the source editor might quickly flash when loading the page and this could be prevented by just not rendering the source code editor when not needed.

align footer next, prev text with their arrows

align text and arrows (same line)
the current page number is a bit to big for my taste

Optimize for mobile

According to https://developers.google.com/speed/pagespeed/insights/ there is much potential for optimizing the Tour for mobile.

Items to address according to PageSpeed Insights:

Minify code mirror and ui-codemirrors Javascript files 127.4KiB (35% reduction).
Enable Gzip compression for all resources 294.8KiB (71% reduction).

use tour.dlang.io

I already created an A entry to 46.101.210.109, so feel to change your server config.

Docker: make sandbox configuration available through env variables

The following configuration block should be configurable through environment variables in the Docker container:

    # For docker driver
    config:
        memory_limit: 256
        maximum_queue_size: 10
        time_limit: 10
        maximum_output_size: 4096

This is needed to adapt to different production servers.

Use CDNs where appropriate

Bootstrap, Angular and maybe other libs used support using CDNs. So more bandwidth is saved on the servers running the tour because basic libraries are loaded from e.g. Google CDN. And loading the tour should be faster because the client either has those libs cached already and is able to open more concurrent connections.

Don't make bottom fixed in browser

As per Bubbasaur's suggestions, don't make the bottom bar fixed as it is a waste of space. The behaviour just has been copied from the Go tour.

Program caching doesn't work correctly with final Docker container

Caching of program output doesn't work with "final" Docker container that is deployed on dlang-tour.steinsoft.net.

use "new" dlang.org logo

The new logo with the planets and the arc looks a lot better!

Push a notice to dlang.org after first milestone

Your dlang tour already looks great, there are a couple of small issues, but you definitely should get this public soon! This is great!

make text and code box fixed height and allow scrolling

again this is just an idea.
The idea is that both the left text and the right text box have a fixed height, so that the reader can always see the navigation menu at the bottom.
Moreover decoupling the two views allows to scroll in the code box without the text moving with your scrolling.
We could map the common navigation key (key {up,down}, page {up, down}) to currently focussed box and by default to left text box.

Validate user output

In the node world Nodeschool is pretty popular:
http://nodeschool.io/#workshopper-list

You can see its online version here: http://generalhenry.com/

Their idea is pretty simple - download this guide and verification tool. Run it afterwards on your output to validate whether you did the right thing. Maybe the dlang-tour could do something similar to all those
algorithm contest websites (e.g. hackerrank supports D) and check the user output.

Convert comments on function examples to /** */ style

As phobos does it all comments should have the /** and */ syntax for comments.

Add link to GitHub repository in webinterface

Add something like a "Fork me on GitHub" or report issues on GitHub button somewhere on the webpage (without being too intrusive) so that users can report issues and send pull requests directly to the right place.

Expand content with no source and add Playground button

Content should be expanded if source code is empty. Add a playground button which hides/shows the D playground editor.

Mobile-friendly/responsive view

After having had a look at the Go and Rust tour, which are both nice to read on one's phone - I think we can do a better than this

Some ideas

move the example code below the text on mobile
use the responsive dlang.org menu
-...

Allow language selection

The content and the internal content representation have been designed to allow translations but this should be also reflected in the frontend and made available to users.

Expand source code editor if space is left

According to Mark Isaacson's comment:

My one complaint is that the section of the screen that contains the code doesn't scale well vertically when my browser window is large. The written explanations scale to fit the content, the code editor does not. I'd just make it stretch vertically to fill the screen :). At that point you might also consider putting the Run/Reset buttons at the top.

content left, code right

As we all are used to read content from the left to right, it makes sense to have the explanation and description on the left as the GoLang Tour does.

Graphically show compile errors

Compile errors should be shown graphically by e.g. putting the erroneous line in red.

Collect telemetry about usage

Collect visits per section, number of compiles (incl. failures) and create overview page to show usage stats of the tour.

move over to official dlang repo

probably makes sense to move it over to dlang, s.t. other people can help to maintain this and it's gets visibility and an official status.
Ping @CyberShadow

different theming than dlang.org

compared with:

I actually separated the menu from the other JS on dlang.org, so it should be easy to use.
See e.g.

https://github.com/dlang/dub-registry/blob/master/views/layout.dt

https://github.com/dlang/dub-registry/blob/master/public/scripts/menu.js

and https://github.com/dlang/dub-registry/tree/master/public/styles

collapsible menu at the left side

this is just an idea, but I feel more structured in this way.

live

Optionally we make the entire menu collapse/ toggle-able.

Use SSL

It seems to be a general trend to use ssl and nowadays Google puts that into their ranking too. Thanks to the letsencrypt project we can have ssl for free :)

Take inspiration from tours of other languages

Hey I accidentally came by a couple of such tours or schools, lately and I thought I post this list here as a starting point for inspiration and further ideas. Have fun browsing.

http://rustbyexample.com/
http://twitter.github.io/scala_school/
https://tour.golang.org/
http://nodeschool.io/
https://phpschool.io/
http://tryruby.org/

Interactive tutorial for third-party libraries?

Hi! I'm developing a library that generalizes ranges so they can be used in more contexts like for example async IO and metaprogramming. In the long term I plan to propose it for std.experimental, but first I need to introduce people to some new concepts and techniques, before I can convince them that it's a worthwhile addition.

So, obviously I was thinking about making a tutorial for my library, but then I noticed your project and I thought that it would be great if I could use it to present my library and to let others play with it.

What do you think about letting other people make tutorials about their libraries and to publish them on dlang-tour (of course, after your permission)? This would require some basic dub support (in order to specify external dependencies) and maybe some small reorganization (maybe adding a third-party drop-down, next to vibe-d).

Speaking of DUB, I'm willing to contribute a tutorial for it, but I haven't looked at your backend code, so I don't if it would be a large effort to support it in addition to rdmd.

edit this page button

Would be convenient if we would have an edit this page button, s.t. people can easily reach this repo and help to improve the content.

Correctly escape source code before inserting into source editor

Some source code code might break the page layout.

a lot of whitespace at the footer

just a nitpick, but probably easy to remove this space.

Support mobile devices correctly

The Dlang Tour is using Bootstrap but the layout should be tweaked to at least support mobiles devices like IPads. I have an IPad Mini and the layout break the content and the source code editor in two rows which looks weird. I would be in favour of also having the source side by side to the content.

dlang-tour / core Goto Github PK

core's Issues

Recommend Projects

Recommend Topics

Recommend Org