search

google / docsy

A set of Hugo doc templates for launching open source content.
https://docsy.dev
Apache License 2.0
2.61k stars 901 forks source link

"See Also" #446

Open Symbolics opened 3 years ago

Symbolics commented 3 years ago

Has anyone got a way to put a 'See Also' section at the bottom of a page? Ideally in some kind of collapsible format. This is a good way for a developer to point users to things that are likely going to be the next thing to read.

LisaFC commented 3 years ago

For my own docs I tend to just do a regular section with a header called What's next? or Related pages or similar.

Do you want it in a different format to a regular paragraph, like a notebox? Autogenerate it in some way? I know the Istio.io site (which uses Hugo but not Docsy) has "See also" sections that (I think) are autogenerated from keywords. Here's an example: https://istio.io/latest/docs/concepts/traffic-management/#see-also

There may be something in their site code you could borrow.

Symbolics commented 3 years ago

That would work. I guess I was thinking mainly in term of visual style. Perhaps something like this:

see-also I wonder how open source project encourage web design type folks to join? Seems one of our issues is no one here is really good at this web stuff.

LisaFC commented 3 years ago

Yes, I agree it would be nice to have more experienced web/frontend designers contributing and that's certainly something we should look at how to encourage - though we have had some great community contributions in terms of site functionality and design in the past (and I do know basic CSS, Bootstrap, and Javascript, I'm just not very fast.....)

That said, there are limits to what we can put in the theme - not everyone is going to want the same look and feel for their site and, realistically, our community are going to prioritize new look and feel feature requests that we think many theme users want (eg #349, where lots of users were interested and now a community member is going to implement). I think another more common pattern that we've seen is users implementing features for their own sites that they've, when appropriate, added to the theme if enough other users are interested. There's also possibly a role for our discussion group in helping each other with our site customizations....

Symbolics commented 3 years ago

Is istio.io Docsy? Their 'See Also' would work. I guess the visual style I mentioned above is more a case of what I am accustomed to than any real 'requirement'. If it is Docsy, I noticed that they have a expandable TOC, and I like their TOC icons and sections, e.g. 'Setup', 'Tasks', 'Concepts', etc.

Edit: Read LisaFC's reference to istio.io more carefully. Anyone know what theme they use? Very nice indeed.

LisaFC commented 3 years ago

It is very nice! However, it's not a theme - if you look at the repo you'll see it has no themes dir - it's all custom work for that specific site that (largely) one of the SWEs who used to work on the project did themselves. It has bits borrowed from Docsy in it (and another site I worked on previously), and we've borrowed a couple of bits from them!

It is a Hugo site so if there's any styling, section heading ideas, JS etc. that you like have a look in their repo - though because it wasn't designed to be a theme/reusable so you'd probably have to do some customization/disentangling yourself to get it to work, and some of the icons etc. were designed/customized specifically for that site so you do risk your site looking a lot (too much?) like theirs. (I think some of them are Font Awesome)

(I did some work on the project and wrote that page I linked to, hence my familiarity with it...)

This is a "big" Docsy site that might have more ideas for you: https://kubernetes.io/

Symbolics commented 3 years ago

Looks like they have some web front-end experts working on istio.io. A shame it's not easy to pick that stuff apart, their TOC would nail #342, and provide a great exemplar for what content should be covered in a doc site from a technical writing perspective.

LisaFC commented 3 years ago

Yes, their toggly menus are nice - looks like they use TypeScript

In terms of a great exemplar, our example site has more or less exactly the same TOC sections. :)

(We used the more generic Getting Started rather than Setup because some projects have very little that could be described as setup - it may just involve downloading a library - and might benefit from a quick start tutorial, while others like Istio have extremely complex installation and configuration. We also added an optional tutorials section, where Istio has an Operations section that's really only applicable to a project with DevOps users)

We put the sections in the example site rather than the theme itself because we wanted to keep Docsy flexible for all kinds of doc sites - it's a structure that's applicable to a larger doc set with multiple content types, while smaller sets (like our user guide) may only need a get started/setup, some tasks/how-tos, and examples.

Symbolics commented 3 years ago

Actually you are right. One of the main reasons for us to pick Docsy is that it was an easy to follow example of good quality documentation.

Is there any work or an issue related to cards? That seems like it would be a great feature to add. I think that might be a short-code and didn't see any in the documentation.

LisaFC commented 3 years ago

We don't have an open issue but Kubernetes Docsy site has cards for their docs landing page, you could take a look at what they did - here's the relevant partial: https://github.com/kubernetes/website/blob/master/layouts/partials/docs/docs-portal-card.html