New Beman Website Formal Review

I believe @Jeff-Garland intends to create a thread to launch the review of the new website, but since I have time today to evaluate it, I’ll post my questions/comments here.

My understanding is that there are two approaches being proposed:

@sakshamsharma also created a site, but his comment elsewhere leads me to believe it’s being withdrawn from consideration.

I’m going to focus on the contributor workflow and the tools used. The tech stack does not affect which pages we want on the website so I won’t evaluate that aspect.

1 Like

My experience with @RaduNichita’s site follows:

It would be useful if the instructions explained how to install yarn on various platforms. (e.g. on MacOS use brew install yarn)

I followed the instructions for creating a new blog site, but it didn’t show up on my yarn run call. I killed it and, upon restart, I got a long error message that had buried within it this string: “: Error: Blog author with key “David Sankel” not found in the authors map file.”.

I figured I must need to have an entry in the authors.yml file. Adding an entry there was fairly painful. I needed to figure out what the avatars.githubusercontent.com link would be and decide on a “title”. None of this was mentioned in the instructions.

I tried to start again and got another failure. I realized that I needed to use the “key” of my author entry in the blog post so then fixed that. Finally it started and my blog post came up.

When I made changes to the blog post, the HTML view updated automatically. It was a bit confusing that the top level # didn’t show up in the blog post at all and the title was controlled by the metadata. It would be nice if the title was pulled from the body of the post.

I added some images into my post and I had to lookup how to do that with markdown. It was easy enough and since each blog post gets a directory, placement of the images was straightforward.

When I made my commit, it wanted to add some changes to the yarn.lock file. I didn’t know what this was about, so I just omitted those changes in my PR.

To create my PR, I used gh pr create instead of following the instructions. This was easy enough to do. Here’s the PR: Add NYC++ blog post. by camio · Pull Request #5 · RaduNichita/website · GitHub

My experience with @mguludag’s site follows:

There weren’t any site-specific instructions in the README, but I was able to find local development towards the bottom. Similar to my comment on @RaduNichita’s README, it would be useful to have the dependency installation spelled out for common platforms (brew install hugo, brew install go).

The commands to start the server were more complicated than with @RaduNichita’s and it didn’t start a web browser for me. A small thing.

I followed the existing blog entry to add a new one. I like the name of the main file being index.md rather than blog.md. This seems more conventional.

After creating the .md file and writing to it, it immediately started showing on the Blog site. That was nice.

An issue I noticed right off the back is that in the Blog listing page, instead of showing the image my post began with, it put the “alt” text. This wasn’t right at all and I’m not sure how to fix it.

My PR is here: Add NYC hackathon blog post by camio · Pull Request #1 · mguludag/beman-project-example-static-site · GitHub

1 Like

Here’s a comparison of the tech stacks.

Proposal Stack Stars on Github Org Commits Num sites on github
@mguludag hugo 77.6k N/A Consistenly ~25/week 9.7k
@RaduNichita docusaurus 58k Facebook Big drop mid 2022. Now at ~10/week 4.2k

According to Gemini, docusaurus focuses on documentation websites and hugo is more general purpose. React’s integration with docusaurus, which we aren’t using IIUC, is one if its main selling points.

3 Likes

I’d like to hear from @RaduNichita and @mguludag why you choose your respective frameworks.

Thanks @dsankel for the comprehensive feedback. I’ve modified the README according to your suggestions.

Regarding choosing Docusaurus over other frameworks,

  1. I went for docusaurus since I saw that it is more documentation focused rather than general purpose. Docusaurus uses react under the hood, we still benefit from it using the mdx format (for example Talks | The Beman Project is a mdx file, since it is not possible to embed videos in standard markdown flavour).

  2. I also saw a couple of sites containing well-maintained documentation (Operating Systems | Operating Systems or https://reactnative.dev/ or https://babeljs.io/) using the same framework.

1 Like

Thank you @dsankel for the detailed feedback and findings! I have added setup scripts for mac and ubuntu based on your suggestions. And the image caption shown bug in the blog list I fixed it and added style to show on bottom of image with background.

My opinions and experiences to choosing Hugo over others,

Sorry I didn’t so thanks for doing that!

That’s correct he was briefly on the meeting and endorsed focusing on these 2 options. I think his might have also been Hugo.

1 Like

I want to provide some concluding thoughts for my review. First, thanks to both @RaduNichita and @mguludag for building out these websites. I think both explorations are of high quality and substantially better than what we currently have.

When it comes to usability, @mguludag’s approach, where blog posts are not tied to a separate authors’ file, simplifies things for contributors. While @RaduNichita’s has the edge in README.md documentation, the simplified blog post approach won out for me.

As far as framework risk goes, Hugo is roughly twice as popular as Docusaurus and doesn’t have the drawback of being owned by a single company. The fact that there was a big drop in commits mid 2022 for docusaurus concerns me. So, while they are in a similar tier, I think Hugo wins out.

In conclusion, I think both approaches would work well, but I recommend proceeding with @mguludag’s approach.

So I have been doing a little research that isn’t so much hands on, but more down the direction the full potential of what’s possible with static generation sites. That is moving the goalposts perhaps. Part of this is that both of these options for the basic things don’t really separate substantially like you found @dsankel. Note that I’m not terribly concerned with the ‘single company’ element as the project is fully open source.

So additional things we can imagine doing with the site:

  1. allow comments on the blog through discourse
  2. maintain combined code-reference docs (multiple versions)

Here’s an example of the first one – which doesn’t use either of the frameworks here. And some discussion on the discourse side. Both use some javascript stuff maybe with iframes to accomplish this – doesn’t look super easy.

The second item is the more important thing I believe. Libraries need to maintain docs and it’d be great if we could have an integrated doc set – or at least consistency in docs that the website could point to.

This second item is what has me thinking docusaurus has an edge – have a look at them eating their own dog food. Don’t miss on the right that with a trivial dropdown earlier versions of docs are maintained. Of course it’s generating sites with react.js instead of more static html like Hugo – so it has some advantages.

Also note:

From my understanding search is built-in – and if that’s the case I think it would be difficult to beat.

This is preliminary at this point, but what I’m thinking about and looking into – I thought I’d share so others can think about as well.

Hugo has builtin support for disqus and the theme supports giscus (github discussions) additionally. I looked how I add discourse comment system as a plugin then I found a way and introduced discourse comments plugin here: add discourse comment system · mguludag/beman-project-example-static-site@8c9c63b

For versioned code documentation, if we use doxy style docs in code, we can be able to parse it and generate the md pages from it when we create a tag for library and ci creates a PR to website repo for this versioned documentation. (e.g. create tag 0.3 for beman-libxyz → ci parse and create md files under content/docs/beman-libxyz/0.3/ → then ci create PR for it)