ipfs
Enhance the docs by using the IPFS Glossary more creatively.
This issue is one of the prioritized recommendations in the Q1 2020 IPFS Ecosystem Audit for execution in Q2/Q3 2020. Tagging it with $auditrecommendation means it's searchable! See all tagged issues in this repo.
We now have an IPFS glossary for the docs site, but a lot more traction could be gained for this by ...
- Adding more terms and definitions
- Creating condensed (single-phrase with link) versions of those definitions for use throughout IPFS docs in hovertext (as discussed in Q3 2019; we even visually mocked up some options)
- Implementing those hovertext tool tips
This effort is valuable on its own, but even more valuable considering that no other similar resource for the dweb exists today.
Just joining this thread to get a heads up when there's movement on this, as we were talking about something similar in a Filecoin docs call today. ❤️
Interesting! Was it to do with creating a JS hover widget for these terms? As I was talking to David recently about how useful a plugin like that would be to everyone if applied across our products.
discussed and explored many 🌔 s ago https://github.com/ipfs-inactive/docs/issues/372
Yeah, we were discussing adding a hover to the Filecoin specs rather than linking out to a separate glossary, and wanted to follow your work in case it was easy to integrate into VuePress for the Filecoin docs as well. Note that lotus docs have something similar now (https://lotu.sh/), although it appears a bit far from where you click in my opinion. But the lotus docs will soon be integrated into our standard VuePress docs since we're no longer supporting multiple implementations.
Also note ProtoSchool issue #99 about replacing our infrequently used "useful concepts" boxes with a hover glossary solution. Megahertz had shared a nice hover glossary feature from an old company of hers:
Her old company the USA? That was my site, with the flyout glossary. :)
I don't recall that we ever implemented a tool-tip-style one triggered on hover, but that could work. A dotted underline is one way to call out the terms. Agreed re the lotus positioning.
Ha, yes, her company the government. I forgot to drop in the link to the new version of the URL she'd given me as an example: https://beta-nrrd.app.cloud.gov/
That's the one, albeit … different. And with hovers! I may be able to get some insights into how well they perform.
I will say that a little goes a long way. Documented guidance re how to pick words to define, etc, would be super helpful.
Reached out to a current 18F UXer for NRRD …
- The drawer-based glossary wasn't cooperating with material ui, which they've implemented more recently
- I believe the tooltip is a stock Material UI component
- The
?icon seems to telegraph its meaning well to users - Overall it seems to be a useful feature
I like it. But I'd like to see a turn tool-tips off option somewhere. This isn't critical, just something that would be nice to have.
Not sure where it would go, but it might fit nicely into a Settings menu alongside a Dark Mode theme.
I think we did this, to some extent here: https://docs.ipfs.io/concepts/glossary/
