When to merge as a "release candidate"

[budparr]

Here's the current version: https://hugodocs-170426.netlify.com/

Still plenty to do, obviously, but being that the site it will be merged into is also in beta, it seems to me it would be good to get the new design into the wild so people can comment, etc.

I suppose what I need to know are what the critical missing elements that need to be done before that can happen.

note: to make the current design live in any form, I guess we'd have to hide the links to the new main site and news section, because I don't know when anyone intends to merge them, and if anyone has decided what they want to do with URL's etc.

cc @bep @rdwatters @digitalcraftsman

[rdwatters]

@budparr I definitely have some work cut out for me on Sunday 😄

If @bep and @digitalcraftsman (and the rest of the team) are okay with putting this out in the wild, I'd say we set this as the theme on hugodocs.info so that we aren't asking for feedback from the community for a third URL. I'm not terribly attached to my current "design" anyways.

Then I'll work with Lars over the next week to create the list that Bjorn requested re: the pages with most pronounced changes, and then we can hopefully set a solid date for (finally) merging this into master.

After we merge, I'll work with Netlify to set up redirects, etc to keep any links on the forums and issues from breaking. I can buy the domain for the next 24 months.

Thoughts?

[bep]

@rdwatters

1. Don't spend too much time creating that list. find or similar in current Hugo repo similar should be able to list the "files bigger than n bytes". Should not be too many.
2. Also, don't spend time on redirects. That sounds like a waste of time. I think it will confuse fewer people if you close that site down when we go live.

I'm not a big fan of dragging things out in time -- it doesn't need to be perfect to be released. Netfliy enables a pretty smooth release process, so once it is "good enough", just get it out there, and improve as we go. Hugo is a small community, with no big QA department to look for pixel imperfections :-)

Once the site is in one repo with new design, it would be cool to do one round of reviews -- I'm not thinking copy-edits here, more on a structural level.

It would be cool if someone would suggest an effective way to do that.

On a slightly and totally different topic, the link provided in the first post here looks absolutely fantastic, but I get a feeling that the font sizes in the main title vs ingress vs body text look slightly disproportional in my browser ...

[rdwatters]

I noticed the same w/r/t the signature being a bit on the large side. BTW, this looks great and I was hoping you were going to do something similar to MDN, which you did, which is super cool. Do you think it needs a "Signature" or "Syntax" heading above it? Here's the way it's presented on MDN. This isn't a strong opinion; more like spitballing:

I also should have mentioned @budparr that the site does in fact look freakin' fantastic, so thank you so much for all your hard work on this 😄

[rdwatters]

Okay, and while looking at the signatures, noticed that when @moorereason added more than one signature, they aren't separated by a line break, for example:

https://hugodocs-170426.netlify.com/functions/index-function/

[budparr]

@rdwatters I'll add that last bit as a new issue. Thank you.

[digitalcraftsman]

After having a look at the current state of the docs I compiled this lists of things that I would like to see in the release candidate:

Syntax Highlighting

Beside the actual documentation the docs also feature a large portion of example code. Syntax highlighting make the reading of the example code much more pleasant.

Furthermore, most code examples are to wide in order to fit into the middle column for the text. Currently, this is solved by expanding the code container when the users hovers over it with the cursor. Therefore, I would make the code containers wider than a line-width for text.

@bep already created in issue for the latter paragraph: #15

In-line code examples

The font-weight of in-line code examples makes them look a bit weird on contract to the regular content. A different background for in-line code as GitHub does it with a thicker font (i.e. a higher font weight) might be a better alternative.

Table of contents

The TOC shouldn't hover the footer with the prev/next links like on this page.

Quotes

Quotes can't be identified as such. There is a colored border on the left to indicate it "but what does the green color mean?" could some users ask. Ryan's initial design featured small icons such as an i to indicate an info or ! to indicate a warning. A quotation mark like “ could be used as well.

To be consistent with all kind of this blocks shouldn't have a left margin.

[budparr]

Thanks. I've recorded the ones that didn't already have an in issue in a new one.

[rdwatters]

@budparr , so that I don't get out of line with scope for this issue thread, would you prefer I (and others) open individual issues during our review? Seems like double work for you to open these up based on comments. Thoughts?

[budparr]

yes, please.

[budparr]

I think this is on everyone's radar and we have issues filed. so I'm closing this. Thanks!

[budparr]

Milestone for the release issues: https://github.com/budparr/gohugo-theme/milestone/1