Website redesign feedback

[kristoff-it]

I've been working for the last few weeks on a redesign of the website. I haven't changed the general graphical theme, but I've expanded the number of pages and restructured the front page drastically.

The work is being done in the hugo-redesign branch and unfortunately at the moment is a bit hard to get it working on your machine as it depends on the docgen tool. I'm working on a simplified version of it, but it's not ready yet. In the meantime you can preview the website here: http://ziglang.github.io/www.ziglang.org/

The main (but not sole) goal of this redesign is to make the site more accessible for the average developer who might not appreciate the in-depth overview of Zig that's currently present on the front page.

For this reason the in-depth overview has been moved inside the learning section, while the frontpage acts as a more general introduction to the Zig project as a whole, starting from the language itself, to the community and the Zig Software Foundation.

The main type of feedback I'm looking for at the moment is about the copy (i.e. the text), especially when it's small fixes that improve the wording or in general provide a more effective way of expressing what the text was trying to say in the first place. If you think something needs big changes, please provide adequate explanations and consider the impact on the surrounding text. For example, changing the "Performance and Safety" point with something else, will probably require to rethink the other two points as well.

Please try to keep the discussion focused on actionable points, if you want to have a general discussion and / or ask questions about what I'm trying to achieve with the website, please do so on Reddit: https://old.reddit.com/r/Zig/comments/jtjmq5/ziglangorg_redesign/

[marler8997]

First, thanks for working on this, the situation can definitely be improved.

I'm not a great designer but I do have one suggestion. I really like the high level overview, and I think it's a great resource that gives people an idea of what Zig looks like and how it "feels" very quickly. For new users, I expect it will be the 2nd thing they want to see (after seeing a summary of what the language offers). However, the new design hides it behind the "Get Started" button. For me personally, when I'm looking at a new language I'm looking for "information" before I commit to going through a "Get Started" link, which I would guess talks about how to download the compiler and contains something like a tutorial, but at first I'm not looking at how to use the language, I'm trying to learn about the language first.

I'm not saying we need to include the high level overview on the main page, but I think it should be at most 1 click to get to it, and it should be obvious it exists on the main page and one of the first things a user sees.

[DeadWisdom]

Messaging Suggestions:

• "A simple language" -> "Simple, Powerful Language"
  The wonder of Zig, at its core, is that it allows complexity while being simple. Many people will see "a simple language" as being a toy.
• "Comptime" -> "Compile Time Execution"
  Comptime might not mean anything yet to novice users.
• "Performance and Safety" -> "Performance & Safety"
  Fine words, to the point, "&" is often used for short headlines.

I would personally love hyperlinks on all the bullet points to where in the documentation I can read more about that. Even better if it switched the code sample to be a sample for that with a button below that says "read more".

Formally offering my services for design and development. I'm out of work right now, so I'd do it for free, but would also be grateful for being thrown some pay for it.

[Mouvedia]

Before making the switch, get metrics.

e.g.

• how many go past the fold
• how many reach /download/ through the landing page
• how many click on the donation links
• etc.

menu

• documentation/master/ should be accessible directly from the menu
• the menu should be an ul
• list elements should have white-space: nowrap;

[pfgithub]

Some possible code snippets for the Code Examples page

Example of fizzbuzz

const std = @import("std");

pub fn main() void {
    var i: usize = 1;
    while (i <= 100) : (i += 1) {
        if (i % 15 == 0) std.log.info("FizzBuzz", .{}) //
        else if (i % 3 == 0) std.log.info("Fizz", .{}) //
        else if (i % 5 == 0) std.log.info("Buzz", .{}) //
        else std.log.info("{}", .{i});
    }
}

Example of a generic type

// test with `zig test generics.zig`
const std = @import("std");

pub fn Queue(comptime Child: type) type {
    return struct {
        const This = @This();
        const Node = struct {
            data: Child,
            next: ?*Node,
        };
        alloc: *std.mem.Allocator,
        start: ?*Node,
        end: ?*Node,

        pub fn init(alloc: *std.mem.Allocator) This {
            return This{
                .alloc = alloc,
                .start = null,
                .end = null,
            };
        }
        pub fn enqueue(this: *This, value: Child) !void {
            const node = try this.alloc.create(Node);
            node.* = .{ .data = value, .next = null };
            if (this.end) |end| end.next = node //
            else this.start = node;
            this.end = node;
        }
        pub fn dequeue(this: *This) ?Child {
            if (this.start == null) return null;
            const start = this.start.?;
            defer this.alloc.destroy(start);
            this.start = start.next;
            return start.data;
        }
    };
}

test "queue" {
    const alloc = std.testing.allocator;

    var int_queue = Queue(i32).init(alloc);

    try int_queue.enqueue(25);
    try int_queue.enqueue(50);
    try int_queue.enqueue(75);
    try int_queue.enqueue(100);

    std.testing.expectEqual(int_queue.dequeue(), 25);
    std.testing.expectEqual(int_queue.dequeue(), 50);
    std.testing.expectEqual(int_queue.dequeue(), 75);
    std.testing.expectEqual(int_queue.dequeue(), 100);
    std.testing.expectEqual(int_queue.dequeue(), null);
}

Example of c interop

// build with `zig build-exe cimport.zig -lc -lraylib`
const ray = @cImport({
    @cInclude("raylib.h");
});

pub fn main() void {
    const screenWidth = 800;
    const screenHeight = 450;
    
    ray.InitWindow(screenWidth, screenHeight, "raylib [core] example - basic window");
    defer ray.CloseWindow();
    
    ray.SetTargetFPS(60);
    
    while(!ray.WindowShouldClose()) {
        ray.BeginDrawing();
        defer ray.EndDrawing();
        
        ray.ClearBackground(ray.RAYWHITE);
        ray.DrawText("Hello, World!", 190, 200, 20, ray.LIGHTGRAY);
    }
}

Example of memory leak detection

const std = @import("std");

pub fn main() !void {
     var gpalloc = std.heap.GeneralPurposeAllocator(.{}){};
     defer std.debug.assert(!gpalloc.deinit());
     
     const alloc = &gpalloc.allocator;
     
     const u32_ptr = try alloc.create(u32);
     // oops I forgot to free!
}

Other possible snippets that could be useful

• Arena memory allocation
• Error handling with try / catch / if and defer / errdefer
• "Use comptime to write release-aware code" (comptime alternatives to #ifdef)
• Optionals and if / orelse
• constructing structs with @Type()
• basic io like reading from stdin and writing to files
• exporting a c library
• std.json
• packed struct bitfields
• async/await
• build system

[kristoff-it]

First, thanks for working on this, the situation can definitely be improved.

I'm not a great designer but I do have one suggestion. I really like the high level overview, and I think it's a great resource that gives people an idea of what Zig looks like and how it "feels" very quickly. For new users, I expect it will be the 2nd thing they want to see (after seeing a summary of what the language offers). However, the new design hides it behind the "Get Started" button. For me personally, when I'm looking at a new language I'm looking for "information" before I commit to going through a "Get Started" link, which I would guess talks about how to download the compiler and contains something like a tutorial, but at first I'm not looking at how to use the language, I'm trying to learn about the language first.

I'm not saying we need to include the high level overview on the main page, but I think it should be at most 1 click to get to it, and it should be obvious it exists on the main page and one of the first things a user sees.

Thank you @marler8997 for your interest. You raise a good point and I think I'll be able to satisfy your request. I'm thinking of adding two buttons somewhere in the 3-point section. One for the in-depth overview and one for the other code samples. I don't know yet precisely how it will look like, but please check back in a while and let me know if you think there should be another change made in that regard.

[kristoff-it]

Hi @DeadWisdom,
thank you for answering on the part of the website that I'm most interested in discussing right now.
I'll say upfront that since I spent a good chunk of time thinking of the small details I'm pretty opinionated but if you are willing to continue the exchange I'm happy to continue as well.

Now, onto the points:

Messaging Suggestions:

* [ ]  "A simple language" -> "Simple, Powerful Language"
  The wonder of Zig, at its core, is that it allows complexity while being simple. Many people will see "a simple language" as being a toy.

I don't want to add "powerful" because, on one hand, I think it's so over-used that it lost any meaning (all general-purpose programming languages claim to be powerful), and on the other hand I think nobody is going to mistakenly assume that a lower level programming language with manual memory management, pointer arithmetics and C interop is a toy language. That's a problem that maybe languages like Lisp or Tcl might have. Given the goal of enticing people that have never tried programming in a language like Zig/C/C++/..., we should aim to look as non-threatening as possible in the main intro in my opinion.

* [ ]  "Comptime" -> "Compile Time Execution"
  Comptime might not mean anything yet to novice users.

I want to keep comptime because it's the "branded" name of the specific type of compile-time execution model that Zig offers. If we put the more generic term as the title then I don't know where else to put it. Comptime is easily the most exciting feature of Zig that people coming from Python / Java / ... can immediately appreciate, and I want to make the word "comptime" a common term that makes you think of Zig, kinda like "lifetime" is a term that now makes you think of Rust.

* [ ]  "Performance and Safety" -> "Performance & Safety"
  Fine words, to the point, "&" is often used for short headlines.

I'll have to see how it looks on mobile (where it wraps), I'm not sure having "Performance &" on one line looks good. I might be wrong though, I really have to see it first.

I would personally love hyperlinks on all the bullet points to where in the documentation I can read more about that. Even better if it switched the code sample to be a sample for that with a button below that says "read more".

At the moment we don't have any established graphical language for making headers links that send you to other pages. I'd have to tinker with it, but I think as a more economical compromise I can add links to some keywords. It also depends on the available materials, since at the moments some things, like docs for std.GeneralPurposeAllocator aren't ready yet. We can ofc write more content, but it takes effort and makes maintaining the website harder. I'll add some links in the next few days, please check back and let me know if you have other recommendations in that regard. As for having interchangeable code samples, the current plan is to have a JS-free website with maybe a little bit of it to enable some secondary function, but the main functionality of the website should not depend on JS being available. Also, check my reply to @marler8997 wrt adding a read more button.

Formally offering my services for design and development. I'm out of work right now, so I'd do it for free, but would also be grateful for being thrown some pay for it.

For this first pass, I'm focusing on the structure, the content, and other details related to adding i18n. Right now I don't think I'm able to come up with self-contained tasks where you would be able to work independently. As you can see I haven't really changed the graphical design. The theme is basically the same, except for some minor refinements. Once we're done with this work it would make sense to open the floor for a restyling where you could design a new look that leverages the copy and general structure I've created. In that case, it would be much easier to accept a full package developed by somebody else, and it would also make sense to pay for that service. I can't make any promise, but keep an ear out in case we do make a related announcement a few months from now.

[kristoff-it]

Before making the switch, get metrics.

e.g.

* how many go past the fold

* how many reach /download/ through the landing page

* how many click on the donation links

* etc.

The current plan is not to add any JS to the website. Additionally, adding JS that doesn't provide any functionality to the user, but just tracks their behavior is even more problematic. Finally, the switch from the current design is happening anyway, so the tracking information would be useful for running A/B tests, where A is the current redesign, and B is a variation based on what I'm making now. In economical terms I think this would be very bad use of the money donated to the ZSF. We have the luxury of not being clueless marketers trying to appeal to a public we fundamentally don't understand, so even without metrics, I'm confident the end result will easily land somewhere above 2 std devs from the average website quality, even without data.

I can confidently say we prefer getting less conversions over tracking our users. Also, real A/B tests that do produce results require a lot of effort and often times produce only marginal improvements (if you're running the test correctly, instead of trying to please your manager).

menu

* documentation/master/ should be accessible directly from the menu

* the menu should be an ul

* list elements should have `white-space: nowrap;`

All these statements lack proper supporting arguments. Maybe they're all obvious for you, but not for me.

[kristoff-it]

@pfgithub thanks for the code samples, I've created #79 for this discussion, let's move it there.

[macarc]

I think the top menu on mobile could be improved from the original design - on mobile, it just has 'download & docs' with a burger icon next to it and that feels unclear - to the new visitor it seems like it is saying you are already on the documentation/downloads page, or at least it is non-obvious what it is saying.

I think either get rid of the text on mobile and just have a burger icon, or do something else to make it clearer that the 'download & docs' text is a link, not a heading.

Re text, it looks good. A few minor points:

• 'Code of Codunct' -> 'Code of Conduct'
• 'A simple language' -> 'A Simple Language' (or change the other headings to only have caps at the start)

[kristoff-it]

@macarc thanks for the suggestions, I think you make a good point for the mobile view, do you have any recommendation on how to make it clearer that that's a menu item? Maybe changing it to "Home"? Any other idea? Also I'm going to fix the other two points, thanks.

[macarc]

Changing to 'Home' would work, especially if it changed depending on which page you are on (so on the 'Tools' page it would change to 'Tools'). Maybe also style the current page heading differently from the other items in the menu? Not too much though, maybe just make it bold or something.

...also a nitpick: the CSS with the menu is a bit off, e.g. the top item ('download & docs') is slightly unaligned with the items below it on mobile, and the padding below and above the top item is slightly different.

[Mouvedia]

menu

* documentation/master/ should be accessible directly from the menu

* the menu should be an ul

* list elements should have `white-space: nowrap;`

All these statements lack proper supporting arguments. Maybe they're all obvious for you, but not for me.

1. accessing the documentation should be easy, right?
2. when using HTML it's recommended to use semantic tags hence why a list should be a list
3. try resizing the browser's window in the x axis, the elements in the menu will wrap in between words; it's less readable