[Prototype] Explore moving the Knative site out of Hugo

[omerbensaadon]

Please leave all comments on the proposal: PROPOSAL: UX/29 Revamping Knative.dev

[julz]

Hacked out a mostly working version and deployed it to github pages so folks can have a click around:

https://julz.github.io/docs/v0.20/install/

Anyway, I think it looks pretty, the search seems quite good, there are some navigation options to try (I picked some that seem nice to me), has really nice tool tips and collapsables. Dev-flow-wise you can run mkdocs serve locally and get live previews, and I think it should be pretty easy to wire up netlify PR previews with this.

Current missing things/todos/to-solves (there are probably more, these are off the top of my head):

• Haven't imported the community stuff tab at all that requires a cross-repo import.
• Reference tab works, but the TOC isnt as nice as Id like
• Need to figure out what to do with the blog if we do this. Mkdocs can do a simple blog which I think is all we need so should be fine, but this is one area where hugo is clearly better.
• There are probably a few broken links around I didnt catch
• The versioning flow works, but needs some manual work to import previous versions
• I copy pasted the artifact macro everywhere because I couldnt be bothered to learn how to do it in one place yet
• Youll get errors when you build because there are some files that do things like import READMEs as index.. these are all easy to fix I think and dont affect the output, theyre just ugly and I didnt fix em yet
• Set up with netlify and do PR previews etc
• Opportunities to use more mkdocs features, especially the nice tabs, disclosures, and admonitions in more places
• Probably other unknown unknowns because Im not that familiar with our existing stuff :(

[RichieEscarez]

I think in general, these things can be added to our current site (some have been in the backlog for a long time now). It's always boiled down to the balance between priorities and resource.

One thing that I think is missing in these lists are the specific pain points these items are solving, they are very general as listed but I'll try to address them.

User-facing concerns to address:

1. Does it look better than our current site?

How is "better" defined here? In general, CSS can change for any site so "better" can be added.

2. Does it have good search functionality out-of-the-box?

I believe this is a configuration that needs to be done for every site. Known bugs knative/website#140 knative/website#46

We have all 5 versions building into the same site today, thus the search results show all by default.

3. Is the navigation more legible/better than our current site?

Same CSS comment above. What is the desired change?

4. Does it have built-in Tool Tips + Collapsable sections?
   You can add HTML to any page. Im sure a Hugo community member has created a tool tip shortcode so this is a matter of adding it.

Same for collapsable sections. knative/website#98

5. What does it make our Homepage look like?

Same CSS comment above

Infrastructure concerns to address:

1. Can we merge the website and docs repos as a result of this move to decrease overhead?

We separated them intentionally to prevent someone from taking down the site but I've most recently proposed merging them back together since we are no longer "optimizing users GitHub experience" and just focusing on how content is rendered in the site. The last time this came up, @evankanderson was still advocating to keep the website separate from the docs content.

2. Is it easier to preview changes to the docs site made via PRs?

GitHub actions was proposed as a solution resolve this and add preview builds directly to the PRs. (merging the website and docs repos would accomplish this automatically too). Today, it is disconnected but all PRs are automatically built here: https://app.netlify.com/sites/knative/deploys

3. Is it easies to run and maintain than Hugo?

Today, you just cut new releases and everything it GitHub gets published to knative.dev automatically. Aside from the latest host provider IP change, it runs on its own.

However, adding changes or new features is complicated and done through Hugo (Go based templating site platform that is really fast and already integrated into Netlify).

4. Are builds and automation more transparent?

They are completely accessible today (knative/website and all builds logs: https://app.netlify.com/sites/knative/deploys)

Help docs about everything knative.dev related are in-progress here: knative/docs#2960

5. Basically, is it easier for contributors to understand + use?

Compared to? For context, Kubernetes and Istio also both use Hugo. This is not an easy question given that companies have whole internal teams for their content sites. Given that we dont have a site infrastructure team, this level of complication is not unexpected.

Again, as I mentioned in Slack, I'm open to change especially if im not the only one who went out to read up on Hugo, Docsy, and Netlify. They were all the best OSS tools options at the time.

At the same time, a huge change in infrastructure and file format sounds like more work than address the items above. I think all the above items or changes are all possible in todays site: The first stepping stone would be to manually rebase/sync all the custom Knative files to pick up Docsy features (merge out customizations into the latest versions of the Docsy files that we override): knative/website#231

I hope this is helpful!

[evankanderson]

Infrastructure concerns to address:

1. Can we merge the website and docs repos as a result of this move to decrease overhead?

We separated them intentionally to prevent someone from taking down the site but I've most recently proposed merging them back together since we are no longer "optimizing users GitHub experience" and just focusing on how content is rendered in the site. The last time this came up, @evankanderson was still advocating to keep the website separate from the docs content.

At this point, I'm happy to admit that I'm probably wrong here.

The two benefits I'd hoped for over time were:

1. Easy to update the site "out of sync" with versioned releases of documentation. We have this today with the build script checking out multiple versions of the docs sub-tree, so this didn't need to be a separate repo for that to work.
2. Not disrupting GitHub navigation on knative/docs until the website had started to prove value. The adoption of shortcodes for artifact and tabs was probably the tipping point here.

One other thought (not an objection to merging) is that if we put things together in a hugo-ish way, that probably means moving the current docs content down into something like content/en, so we'll need to update the README and other front-content to make it clear where the actual docs live. We'll also need to update the "edit in github" icons on the page, but that's not a blocker.

[evankanderson]

1. Is it easier to preview changes to the docs site made via PRs?

GitHub actions was proposed as a solution resolve this and add preview builds directly to the PRs. (merging the website and docs repos would accomplish this automatically too). Today, it is disconnected but all PRs are automatically built here: https://app.netlify.com/sites/knative/deploys

It sounds like "netlify preview" is a separate issue from the choice of hugo vs some other templating solution. Thanks for calling this out as an option and an independent workstream.

I'd be happy to help provide guidance/review any actions-based solution; I'm currently working on the sync of OWNERS_ALIASES, but I might be able to work on the action afterwards if no one else has taken it on.

[evankanderson]

For docs building, it looks like Netlify supports a number of different builders, including mkdocs: https://docs.netlify.com/configure-builds/common-configurations/#mkdoc

More interestingly, https://idratherbewriting.com/learnapidoc/pubapis_static_site_generators.html suggests that the search in mkdocs seems to be powered by Algolia; this is built-in with mkdocs, but needs some setup.

• These docs seem well-recommended, but do need some work to be done.
• There's also a write-up from Netlify on their use of hugo and Algolia

[omerbensaadon]

@RichieEscarez and @evankanderson thank you so much for your input!

I think it's probably time to turn this proposal into a Google Doc, send to the mailing list, and take comments, from there.

EDIT: it's a shame that @julz is out this week, would love to get his opinion as well since he exectured on the prototype.

[omerbensaadon]

For future reference for myself (and others): I ought to more fully flesh out some sort of proposal in a Google Doc or GH Issue before I share it out.

It's occurring to me that we wrote this spike very quickly in the UX WG meeting and I hadn't meant for it to be reviewed quite so thoroughly, then again why wouldn't you review it because I shared it out!

[omerbensaadon]

Here is a link to PROPOSAL: UX/29 Revamping Knative.dev

@RichieEscarez @evankanderson I have narrowed in on just a few, more specific things so hopefully you will not have to repeat yourself...

Please view this proposal as more "Let's start work to make the site better" and add whatever you feel needs to be fixed / revamped in the "Background" section.

I'm going to share this proposal with the mailing list once I get a sanity check...

[julz]

Just adding some thoughts from the slack thread to make sure they're not lost:

• I don't think there's a fundamental thing mkdocs can do that hugo cant, or vice versa. Both are highly customizable frameworks.
• Both appear to have decent communities etc and to be used by pretty major projects: It doesn't appear to me there's a "bad" platform here.
• The big question is what we have resources to do. Mkdocs gives us most of what we want out of the box and requires only the expertise and willing hands we have (i.e. - at least - mine). OTOH I simply don't think (happy to be corrected!) we have the design skill and hugo knowledge to fill the same gaps with hugo. That's the fundamental reason Im in favour of mkdocs, and I'd change my mind straight away if someone with relevant skills wanted to donate the time to fix the same gaps in hugo. Again: I think both hugo and mkdocs can make a nice looking site with good search etc but.. mkdocs does it pretty much out of the box - the prototype linked took a day - and does not require skills (hugo, design..) that we do not have.
• There are other issues to deal with in docs, obviously. Informtation architecture etc. I dont think theyre a relevant consideration here. The hands that are able to help move us to mkdocs are not the hands that can effectively help with information architecture (and vice versa). So it just isn't zero sum (though be honest a nice clean design with good whitespace, nice indentation, clear fonts etc may well make readers put up with a lot more poor info architecture).

Thanks much for writing up the proposal @omerbensaadon, and for the feedback/thoughts @RichieEscarez @evankanderson (and on slack) @rhuss @abrennan89

[omerbensaadon]

@julz I am adding these bullets into the proposal!

[rhuss]

+1 to focus on the issue at hand, i.e. the site layout and not on re-structuring the content which is a totally different beast.

[omerbensaadon]

Safe to say this has been thoroughly explored