Documentation Tracking Issue

[austinlparker]

For GA, we need to have docs for each language in GA on the site. This issue will track discovery and implementation.

Please tag any docs issue or PR with the docs label
Kanban: https://github.com/open-telemetry/opentelemetry.io/projects/1

Need To Have

• Discuss/edit this page link
• Search
• i18n
• Accessible

To Do

• Evaluate existing CNCF docs sites
• Create requirements for SIG docs
• Supporting documentation and examples for creating docs in new format
• Write documentation!

[austinlparker]

Adding some notes here for myself/anyone else following at home -

I've started looking into the feasibility of porting the site over to the Docsy theme (used by k8s doc site, most notably). To its credit, it checks a lot of boxes for us out of the box. Here's a preview of what the docs section could look like (most options in the theme are on defaults, so colors/fonts/etc are technically WIP) -

We get a lot of stuff for free with this - deep linking back into GH for issues/edits to pages, automatic revision history slugs, i18n, and significantly better accessibility audits (77 on current custom theme, 91 with docsy, mostly due to better ARIA compliance).

The biggest lift is probably going to be migrating over the registry, but I don't think it'd be that bad all things considered. We'll also need to rework the status page, but that was getting long in the tooth anyway.

[austinlparker]

Pardon the auto-translation, but here's an example of how the multi-language works - you get a dropdown in the corner (these languages need to be defined in config.toml) -

In the repo itself, you just need to ensure that your content is defined per-language -

One thing to note, the language dropdown appears to be global, but there's no fallback to the english text for pages that aren't defined (they're just blank, that's why there's no sections in top nav in the above screenshot, I didn't create the subtrees for other stuff). It's not really a huge problem, I reckon.

[austinlparker]

working on some ideas for the landing page:

[ffe4]

Just stumbled upon your update and not sure what kind of feedback you are looking for, so just my first thoughts here, without really having thought about what the website could/should look like before.

I kind of like having the cards sit on the background like this, but I think the background itself just does not lend itself well to centered content. I also think it would be good to add a bit of a longer blurb explaining what OpenTelemetry actually is on the landing page. Especially since the text about supported libraries and the community on the landing page is much longer than the description of OpenTelemetry itself, which seems an odd introduction to me. Kind of sales-y, if that makes sense.

Integrations deserve to have a separate section/scroll, with more examples than in the card, and maybe also the supported languages, although the fact that we support a lot of libraries might be useful to tease before. The "supported by, and for, the community" part is probably not important enough to be featured that prominently on the landing page IMO.

[austinlparker]

yeah, i'm thinking of maybe doing 3-up for the cards (languages, libraries, integrations) with sort of the "featured" things. I'm also looking at integrating the existing look-n-feel a bit more. Could also just do languages/libraries 2-up then leave the supported analysis stuff at the bottom

[ffe4]

For me, the background is making this a bit awkward. The telescope is the most meaningful object in the picture (as it is our logo), but it seems that whichever way the image is cropped, the telescope will always be mostly covered by other stuff. It just feels kind of wrong to me.

If we want to use the background, maybe just having Get Started, Github, and scroll buttons and a short blurb without a solid background would look better on desktop, but on small screens we probably want a solid background since there won't be much visible of the image anyway.

However, on an actual website, rather than a static image, the effect might also be very different if the site has a parallax scroll that provides more visibility during scrolling. Not sure how much it would bother me in that case. I think a crop like that in the current version of your PR #247 is also a good compromise (even if that crop shows exactly that part of the image that probably almost no one has ever seen before).

[ffe4]

On second thought, having something like this would probably be the best use of the background, assuming we can somehow make the text pop despite the busy image. (sorry for the very minimal effort example)

[austinlparker]

Noodled on it a bit more with your latest suggestion in mind

[ffe4]

I like this one much more! What do you have in mind for beyond the scroll? It would be useful to define what exactly we want to have on the landing page and try to create a consistent layout that also fits the content.

[austinlparker]

Let me push what I have to the preview branch - you can take a look at https://deploy-preview-247--opentelemetry.netlify.app/

[austinlparker]

right now there's some information duplication - I'm not sure how much of what I want on the current frontpage to carry over. I need to start getting the registry ported over though, so that's probably next on my plate.

I see that you're active in python - one thing I've been trying to parse out in my head is how we should handle "minimum acceptable documentation" for each SIG on the site. I don't think it makes sense to force everyone to use this site if they have existing resources that work well for contributors and are "natural" for the community (i.e., readthedocs site for python).

I think it'd make sense for each SIG to at least have a "getting started" for tracing and metrics, and a link to more complete documentation wherever it exists

[ffe4]

Yeah I was thinking about that as well. Defining a couple of common Getting Started scenarios would make the most sense, and I would hope that there is a place for those in each SIG's native docs. I've seen that there are some glitch pages (https://glitch.com/@opentelemetry), but haven't looked at them yet. Is there something useful among those?

I would just make the Getting Started guides the first section under the documentation drop down. I am not sure what the scenarios should look like, but it might be a good idea to define general use-cases we want to have covered, then check with the SIGs to see what they have, and then decide on the specifics once we know whether there are any quirks in some of the languages. Ideally the only differences between the guides would be the code samples.

[austinlparker]

Yeah, those glitch samples are what we use for the official workshops. I was planning on linking to them - it might make a lot of sense to just have that be the basis of the getting started examples...

[austinlparker]

Started a doc for structuring each language's content: https://docs.google.com/document/d/1YyGax0fXZau17hV0lePnGc0LDvKokjFqWb2AhdlbyO4/edit?usp=sharing

[austinlparker]

See https://github.com/open-telemetry/opentelemetry.io/projects/1 for status of individual doc sections

[austinlparker]

In the interest of doing some issue cleanup, closing this as we're pretty much at a solid process at this point (see #472) for the docs content, where it lives, and how it's updated.