Use a wider default style

[karwa]

Swift-doc really doesn't do a good job of using all of the available space.

As a result, it tends to be very uncomfortable to read (at least for me). There's a lot of wrapping, so things like code samples look especially poor:

Removing the max-width: 1280px constraint from body, things look just as clean, but become a lot more comfortable to read, and code samples suffer from much less wrapping:

Obviously, everybody has their own opinions on style and design, but this does seem to be quite wasteful of the available space. Developers will likely spend a long time reading and studying these documents, so comfort and readability should be top priorities IMHO.

[compnerd]

I think that rather than using a wider default style, it may be better to actually use a flex-width container to get scaling based on the current window size. This would be particularly helpful for scaling the documentation from desktop to mobile.

[mattt]

@karwa Thanks for sharing your feedback about the design. I agree that matters of style can be difficult to discuss because of their subjective nature.

There's a consensus among designers that the optimal line length for typography on websites is somewhere between 45 – 90 characters. The current stylesheet follows this guidance.

I think there's a consensus, albeit weaker, among developers that line length for code should be around 80 – 100. I believe the current stylesheet should also follow these guidelines. If they don't, that's something we should address.

swift-doc takes any code formatting as-is. So if your code is formatted to look nice at an 80 character width, it'll look great in the generated HTML.

@compnerd The current stylesheet is mobile responsive. On desktop, increasing the zoom level (⌘+) should magnify text and container widths to use the available screen real estate.

[karwa]

Sure; I just find it very difficult to read, especially for longer bodies of text. It's so bad that it actually gives me headaches.

The reasoning for the 45-90 character length is given as:

Shorter lines are more comfortable to read than longer lines. As line length increases, your eye has to travel farther from the end of one line to the beginning of the next, making it harder to track your progress vertically.

But, at least for my eyes, I'd rather have longer lines so my eyes don't need to reset to the beginning quite so often. There is a balance to be struck, and I can't make generalisations over what all human beings find comfortable -- but then again, that website is making a broad generalisation, so...

It's one of the main reasons I decided to fork this project for documenting WebURL. You can see an example of the results here. I didn't make that change because I think it looks "better" or "nicer" in an aesthetic sense; I did it because I found it more functional - it's easier to consume the information and doesn't give me headaches. I'd rather not use a fork, but as long as the default output makes me physically uncomfortable, I don't see that I have a choice.

I think it would be worth making it an option, at any rate.