documentation style
albertz opened this issue · comments
This is just a suggestion.
Currently, the homepage looks extremely outdated, like something from the 90ies. When I saw it first, I closed it again as I thought this project is probably abadoned since a long time. Only accidently I found later this GitHub repo and was very confused that it is still alive, based on the homepage I have seen earlier. This is not a good impression, esp not for such a project, which is really actually something extremely modern. (Of course, some other people maybe would go the other extreme, declare this as a next-gen terminal emulator in bold fonts, with some very fancy style. This is also not what I'm suggestion here.)
Some options:
-
Maybe changing the background color, the font, and maybe slightly the CSS already fixes this. (I'm really not a web designer, so unfortunately I cannot really help there.)
-
Maybe just use readthedocs.io instead? This integrates nicely into GitHub. You can have the documentation directly in the repository, and every time you push, it will automatically update the docs.
-
Or GitHub pages, and some of the existing default style files (which all look very simplistic and modern).
I'm not sure what makes it "outdated". I think the basic model of a sidebar plus main panel is very functional and elegant. It seems to me it's exactly the same as ReadTheDocs. It works with pretty much any screen or font size, and scrolling works correctly, which many "modern" pages fail to do, I'm old-school and I like simple elegant fast-loading easy-to-navigate web-pages without a lot of bling. I also like pages that don't require a fancy server.
I do think there is too much text on the front page. Probably the "Why another terminal emulator" section should be moved.
"Maybe changing the background color, the font, and maybe slightly the CSS already fixes this"
I'm certainly open to suggestions here. Maybe I can tweak the style to look more like ReadThedocs or GitHub pages, if you think that would help.
Nothing wrong with ReadThedocs or GitHub pages. However, I want to use my own domain name. I also find that in terms of actually writing technical documentation, good old texinfo is still pretty good, and certainly better than Markdown. I haven't found anything clearly better. (Trust me, I've looked: see the use of asciidoctor for help files, which I'd be happier with if the project was more active.) The default html output from texinfo does suck, but DomTerm doesn't use it as-is.
Maybe changing the background color, the font, and maybe slightly the CSS already fixes this
I'm certainly open to suggestions here. Maybe I can tweak the style to look more like ReadThedocs or GitHub pages, if you think that would help.
Yes, I think this already would help a lot. Many GitHub pages are conceptionaly very similar to the DomTerm website, in that they are often very simple as well. However, the style makes it look much more modern.
Please take a look at: http://per.bothner.com/tmp/domterm/
I changed the lightblue used for headers to a even lighter blue, removed the thin border around the headers, and got rid of the uppercasing. I also added a 1em padding around the main body.
Slightly better, but not too much difference.
Look at sites like this, or this, or this, or this, or this, or this.
As said, I'm not a designer myself, so it's hard for me to tell what exactly makes all my links look much more modern compared to the DomTerm site. But it's an extreme difference. I think the colors are very important, and also the spacing of the text. E.g. I think the light green of the left menu is bad. Maybe no different background color from the main text. And there should be more space for the text borders. And I think no background for the title would look cleaner. Maybe a different font face for the titles as well (see my examples). Also the logo itself looks very old.
Btw, also see the website of Hyper, a very similar project, which looks much more polished/modern (and simpler).
I don't really like the Hyper home-page: Personally I dislike white-on-black, finding it harder to read. Also, the home page is too big, with option and API documentation that should be in a different page. I don't find anything modern about it, at least in a positive sense.
The dynmic-gif demo is nice, but the home-page should be just that, plus the "project goals", plus links.
Yes, I agree that the Hyper homepage is too big (it probably was short initially and then grew over time). White-on-black is probably personal taste. You could switch that around. It was mostly an example for a very simplistic style. As well as all my other links. I find that all the links look very simplistic and at the same time very modern, while the DomTerm homepage does not.
I think most important for DomTerm are probably:
- The logo must be improved.
- The colors must be changed.
- Main background just plain white.
- And also the same for the menu.
- No background for titles.
- The text spacing should be increased. (Also to separate the menu more from the text.)
- The text font for titles should be different (see my examples).
If you want to go further:
- Such a dynamic GIF is nice.
- Make the screenshots / GIFs on MacOSX (if you don't have that, maybe Linux with a OSX-like theme). That looks nicer and more modern.
I editing the home page to make it less verbose, which is desirable in itself.
I made some more styling tweaks. Just now I played a bit with the styling of links. I do think it is helpful to keep the traditional blue underline for links, but I made the underline lighter, and changed the background color to match the links in the (now-lighter) navigation bar.
I disagree with some of your preferences. I think the navigation column should have a different background color than the main contents, for example. I like a distinct background color for titles, though I agree a more subtle (lighter) color works better.
By "The text spacing should be increased" do you mean padding? If so, where? I increased the padding around the main text area.
You'd like the logo to be improved. So would I, but it isn't easy - I'm not a graphics artist. I want it to look like a terminal, and I like that it incorporates the text "DomTerm". I think it works well enough that tweaking it is not a priority.
I am not going to make screenshots on Mac, or using a Mac-like theme. That doesn't mean I'll reject contributed Mac screenshots, but I am enough of a GNU/Linux supporter to support that first. I don't equate Mac with modern.
Looks again better, but still not as good as it could be. But I'm also not an expert there. But that is why I linked some of the examples (and I'm sure you can find more good-modern-looking simplistic examples). I'm not sure what exactly is just personal preference, and what is more objective. But do you agree that they all look better and more modern? Or else, maybe search yourself a bit and find some theme / site which really suits your taste.
- Many of the examples have the menu with the same background color. Or if not, they have a box with rounded edges around the menu, but not the whole left side.
- I think sharp edges (not rounded) makes it also look old, like with the title background.
- All the sites I linked have in common, that the titles are not distinct by a background color, but instead by a bold font, bigger font size, and (and that is subtle, but maybe most important) a different font face.
- Most sites have some logo somewhere, sometimes also dominant. In your case, it's quite dominant. But that is why it has a huge impact on the impression about how modern the site looks. I still think this is important. But also, the logo should fit together with the remaining style of the site (in colors, and in general style). Right now, it's mostly grey (which is a color with a not very modern taste). Also, as you want it to reflect a terminal, maybe you should use a monospace font for the
DT> _? Also again for the window title in the logo, I would choose a different font face.
I used MacOSX as an example because they objectively probably invested most money into the best designers you can get. Maybe it's not your taste. But you cannot argue away that design is something very important and of very high priority to them. And also, that for many people, their design choices are nice, and better compared to other things. So if you think about how can you create modern looking screenshots (which are modern looking to many people), using MacOSX screenshots (or Mac-looking screenshots) is not a bad choice. Even latest Ubuntu is somewhat emulating that (the dock, the global menu, etc). When I saw your screenshots, I thought that this is some Linux from 20 years ago or so, which was one of the impression that this project is probably long dead (despite the remaining style of the website, which contributed even more to this impression).
Thanks for your input. I made the logo a bit smaller, and I also fixed how "hover" works over it.
The DT> _ text is "Courier 10 pitch". The logo is created with Inkscape, so changing the fonts is easy. Probably a monospace font without serifs would be better, but I haven't made up my mind. It might also make sense to replace the underline with one of the Unicode block elements, either "full block" █ or "Lower one eight block ▁, but both may be a bit "heavy".
I'm not sure the web-sides you linked to all "look better and more modern". They're fine, but I like the functionality and look of the DomTerm site. (I could probably do with improving my other web-sites.) I may get back to style issues later, but at this point I think it makes sense to get used to what I have before I spend more time on it.
Again, thanks for your thoughtful and helpful advice.