Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Enhance the docs by using the IPFS Glossary more creatively. #294

Closed
jessicaschilling opened this issue Mar 20, 2020 · 10 comments
Closed

Enhance the docs by using the IPFS Glossary more creatively. #294

jessicaschilling opened this issue Mar 20, 2020 · 10 comments
Labels
dif/medium Prior experience is likely helpful effort/days Estimated to take multiple days, but less than a week help wanted Seeking public contribution on this issue kind/architecture Core architecture of project kind/enhancement A net-new feature or an improvement to an existing feature need/analysis Needs further analysis before proceeding P2 Medium: Good to have, but can wait until someone steps up status/inactive No significant work in the previous month topic/design-front-end Front-end implementation of UX/UI work topic/docs Documentation

Comments

@jessicaschilling
Copy link
Contributor

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.
@hsanjuan hsanjuan transferred this issue from ipfs-inactive/docs May 22, 2020
@johnnymatthews johnnymatthews added dif/medium Prior experience is likely helpful effort/days Estimated to take multiple days, but less than a week help wanted Seeking public contribution on this issue kind/architecture Core architecture of project kind/enhancement A net-new feature or an improvement to an existing feature need/analysis Needs further analysis before proceeding P2 Medium: Good to have, but can wait until someone steps up status/inactive No significant work in the previous month topic/design-front-end Front-end implementation of UX/UI work topic/docs Documentation labels May 23, 2020
@johnnymatthews johnnymatthews changed the title Enhance and implement through-linked IPFS glossary/dictionary Enhance the docs by using the IPFS Glossary more creatively. May 23, 2020
@terichadbourne
Copy link
Contributor

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. ❤️

@terichadbourne terichadbourne mentioned this issue Jun 8, 2020
Open
@cwaring
Copy link
Member

cwaring commented Jun 8, 2020

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.

@ericronne
Copy link

ericronne commented Jun 8, 2020 •
edited
Loading

discussed and explored many 🌔 s ago
ipfs-inactive/docs#372

@terichadbourne
Copy link
Contributor

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:

@ericronne
Copy link

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.

@terichadbourne
Copy link
Contributor

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/

@ericronne
Copy link

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.

@ericronne
Copy link

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

@johnnymatthews
Copy link
Contributor

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.

@BlocksOnAChain
Copy link

I think we did this, to some extent here: https://docs.ipfs.io/concepts/glossary/

@Annamarie2019 Annamarie2019 mentioned this issue Mar 31, 2022
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
dif/medium Prior experience is likely helpful effort/days Estimated to take multiple days, but less than a week help wanted Seeking public contribution on this issue kind/architecture Core architecture of project kind/enhancement A net-new feature or an improvement to an existing feature need/analysis Needs further analysis before proceeding P2 Medium: Good to have, but can wait until someone steps up status/inactive No significant work in the previous month topic/design-front-end Front-end implementation of UX/UI work topic/docs Documentation
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
6 participants
@cwaring @jessicaschilling @ericronne @johnnymatthews @terichadbourne @BlocksOnAChain