search

grpc / grpc.io

Repository for the gRPC website and documentation
https://grpc.io
Other
421 stars 447 forks source link

Consider making this a docsy site #107

Closed chalin closed 4 years ago

chalin commented 4 years ago

Consider making this a docsy site, and address the following issues:

cc @thisisnotapril

lucperkins commented 4 years ago

@chalin Could you possibly provide grounds for a potential switch?

chalin commented 4 years ago

April and I were discussing site design improvements, and I mentioned docsy as a possible way of moving forward. It offers a modern look, mobile friendliness, etc.

Btw, no decision has been made to "migrate" to use of the docsy theme (that is why I started the title with "consider").

jtattermusch commented 4 years ago

@chalin we already went through a site redesign relatively recently with very mixed results (there's a number of UI issues with the new look that need to be fixed). Also, the grpc.io site should be mostly about great content and having that content organized in a way that makes sense, not about changing the design once again (users don't care about design, they care about being able to find the right documentation quickly).

I have a list of problems with grpc.io site in a doc - I can share.

chalin commented 4 years ago

grpc.io site should be mostly about great content and having that content organized in a way that makes sense

Totally agree, and it was in this spirit that docsy is being proposed (and the raison d'être of docsy), so that we can focus on content delivery.

I have a list of problems with grpc.io site in a doc - I can share.

Yes please!

lucperkins commented 4 years ago

I guess my question is less why a new aesthetic is being proposed (I’m also jot a huge fan of the recent redesign) and more why Docsy specifically is being proposed amongst many dozens of Hugo themes oriented toward documentation. Personally, I find Docsy pretty lacking from an aesthetic standpoint. It has some decent elements but others, like the landing page and taxonomy pages, I find quite lackluster.

Another CNCF project, Cortex, is using Docsy and I think their site looks quite bad. I’d be happy to jump in and address any design issues but would recommend against a full redesign.

chalin commented 4 years ago

Just to be clear, my intention wasn't to champion use of docsy. This was more invitation to consider it. The Cortex site "works" for me, but as you say, regardless of how it looks, the more important question is whether users find the site convenient to use.

I'll close this issue. We can open other issues regarding specific site features as they arise. Thanks for the brief discussion.

lucperkins commented 4 years ago

@chalin My apologies! I did not mean to end this discussion prematurely, as I do agree that the site could use some intervention. I'll re-open this issue, because I intend to devote some cycles to making things better (free of charge, courtesy of CNCF 😄). We can convert this issue to a "considering our options" issue.

@jtattermusch Could you possibly share that doc with me? My email address is in my GitHub bio. Or potentially transfer the contents to this issue.

thisisnotapril commented 4 years ago

Thanks Luc! It's less about a new look/feel (though I am not opposed to that) and more about what can be done relatively painlessly to make it easier for folks to navigate the site. hence the Docsy mention, since it is supposed to be geared to that. totally open to whatever; just want it to work for the community!

lucperkins commented 4 years ago

@thisisnotapril Gotcha. I'm here to help. I'll address the existing issues in Jan's Google Doc and feel free to assign me to any UI-related issues.

chalin commented 4 years ago

Great! Besides aesthetics, maybe we can have a very brief brainstorming session regarding possible improvements, such as:

chalin commented 4 years ago

But of course, it would be great to get feedback from site users.

jtattermusch commented 4 years ago

@chalin My apologies! I did not mean to end this discussion prematurely, as I do agree that the site could use some intervention. I'll re-open this issue, because I intend to devote some cycles to making things better (free of charge, courtesy of CNCF 😄). We can convert this issue to a "considering our options" issue.

@jtattermusch Could you possibly share that doc with me? My email address is in my GitHub bio. Or potentially transfer the contents to this issue.

Shared.

chalin commented 4 years ago

Addressed in part by #119.

lucperkins commented 4 years ago

We can continue to make bold changes here. The goal of #119 was less to provide a “redesign” and more to put us on a substantially better footing to make improvements. Feel free to keep opening issues.

chalin commented 4 years ago

Coming back to the topic of docsy (which is mentioned in the opening comment, and btw, was the original subject of this issue: "consider making this a docsy site").

On our techdocs Slack channel, @zacharysarah shared a link to https://kubernetes-hugo-staging.netlify.app/docs/home, a preview of k8s.io, which uses docsy. During our last sync meeting @caniszczyk also brought up docsy. Maybe we should give it some consideration? The k8s.io site structure seems reasonable. The way the sidenav, right-side TOC, and breadcrumbs are setup for doc pages works nicely (it would be great if those were generated "for free" -- though I'm unsure if that is the case since I haven't used or looked at docsy in depth).

Thoughts @lucperkins @zacharysarah @thisisnotapril?

lucperkins commented 4 years ago

@chalin Could you possibly clarify why you think we should adopt Docsy rather than updating the existing site and jettisoning every last bit of the work that we've recently done to improve the situation? If there are specific things you want to change I'm happy to provide that. That would entail far less work than porting everything over to Docsy. Frankly, I don't think Docsy would be an aesthetic upgrade at all. It's loaded with broken windows (bad proportions, poorly designed elements) as evinced by the k8s.io redesign. Every project that uses it has to put in significant work to make it serviceable to begin with, and grpc.io would be no exception. It'll be faster and easier to iterate on what we have now; there's nothing in Docsy that isn't easily reproducible within our current framework. I just don't think it's a good project, and recent experience with a range of projects suggests that its perception as a "standard" largely has to do with behind-the-scenes diplomatic pressure by Google.

chalin commented 4 years ago

Thanks for your feedback. I'm not taking sides ATM. Maybe @zacharysarah and @caniszczyk have some opinions to share?

zacharysarah commented 4 years ago

@chalin 👋 Thanks for the invitation.

I think @lucperkins is right to a certain extent: Docsy isn't the best solution for everyone.

Like many themes, Docsy has some coding barriers to entry. One potential barrier is the best practice of installing the theme as a submodule. (Some nuances to git submodule aren't immediately apparent on first use.) Another barrier is the javascript postcss-cli/autoprefixer that the theme requires. For sites like gRPC.io where coding resources are readily available, these barriers are notable but not blockers.

EDIT: Using submodules changes how contributors clone the repo, and it's important to document that contributors need to use git clone --recursive to succeed at building locally.

On the other hand, Docsy is actively maintained and improving, and its behavior is no more idiosyncratic than Hugo itself. (Admittedly, Hugo can be pretty quirky.[1]) Docsy isn't perfect, but I know it's possible to upstream any improvements, and that there's a growing community of support for the theme. Active maintenance correlates to a lower burden for ongoing support, which is always nice.

I value the work that @lucperkins has put into the site's design, and I encourage you to consider past work as a sunk cost. The question is not how well to maintain the past, but how best to support the present and welcome the future.

If you try Docsy and decide you don't like it, it's relatively straightforward to remove. The only considerations would be whether you'd made extensive use of Docsy's block/ shortcodes (which are easy to script back to generic Markdown) or Docsy's swaggerui layout and shortcode (these pages might require significant effort to un-transform once implemented).

Questions

Here are some questions to consider for any theme, not just Docsy:

  1. Does the theme do what I need?
  2. Is there a theme that meets my needs more effectively?
  3. What are the theme's barriers to entry?
  4. What does ongoing support look like?
  5. If I encounter difficulty, how easily can I find help?
  6. Is the theme actively maintained?
  7. How easy is upstream contribution?

TLDR

If it meets your needs, I think Docsy is a strong and valid choice.

Footnotes

[1]: Docsy block/ shortcodes require that if you use reference-style links inside a block/, you must also define the references inside the block. I suspect this happens because of Hugo's list template architecture and isn't specific to Docsy. Credit to @mrbobbytables for the discovery.

lucperkins commented 4 years ago

I'm going to diplomatically bow out of the discussion. If Docsy is chosen despite what I take to be its deep and readily apparent aesthetic limitations, I will respect that decision and not comment further but I will not take part in the transition effort.

chalin commented 4 years ago

Switched back to the original issue title since this was meant to be (and has become) a discussion about the possible adoption of docsy. @zacharysarah, thanks for your detailed comments and thoughtful questions. @lucperkins thanks for offering feedback too.

I'll be making some preliminary assessment and report back here.

chalin commented 4 years ago

Closing this in favor of #479, which offers details of the migration proposal.