Skip to content
This repository was archived by the owner on Jun 2, 2020. It is now read-only.

Test and implement beta nav structure IA #273

Closed
jessicaschilling opened this issue Sep 17, 2019 · 19 comments · Fixed by ipfs/ipfs-docs#2
Closed

Test and implement beta nav structure IA #273

jessicaschilling opened this issue Sep 17, 2019 · 19 comments · Fixed by ipfs/ipfs-docs#2
Assignees
@cwaring @jessicaschilling @ericronne
Labels
dif/medium Prior experience is likely helpful effort/weeks Estimated to take multiple weeks topic/design-ux UX strategy, research, not solely visual design

Comments

@jessicaschilling
Copy link
Contributor

jessicaschilling commented Sep 17, 2019 •
edited
Loading

This issue is part of Epic 2C: Docs beta usability testing and Epic 1A: Launch docs beta.

Continue testing and refinement on the proposed nav structure for docs beta; once confident, implement in VuePress.

  • Decide on what's a page and what's a header
  • Refine text for the titled based on user testing feedback

Keep in mind that this will generate a number of content stubs that need landing pages per #342.

REFERENCE MATERIALS
@jessicaschilling jessicaschilling changed the title Docs beta implementation: Test, refine, implement nav structure [Q4 placeholder] Docs beta implementation: Test, refine, implement nav structure Sep 17, 2019
@jessicaschilling jessicaschilling added topic/design-ux UX strategy, research, not solely visual design dif/medium Prior experience is likely helpful labels Sep 17, 2019
@jessicaschilling jessicaschilling mentioned this issue Sep 17, 2019
Closed
@jessicaschilling jessicaschilling added OKR: Beta Launch effort/weeks Estimated to take multiple weeks labels Sep 19, 2019
@jessicaschilling jessicaschilling changed the title [Q4 placeholder] Docs beta implementation: Test, refine, implement nav structure Docs beta implementation: Test, refine, implement nav structure Sep 19, 2019
@jessicaschilling jessicaschilling changed the title Docs beta implementation: Test, refine, implement nav structure Beta nav structure: test, implement Sep 19, 2019
@ericronne
Copy link
Contributor

@terichadbourne @dominguesgm @cwaring …
Here's a proposed reshuffling which @jessicaschilling and i have landed upon, after a number of tests discussions. Please share your reactions. Hopefully we're approaching a version worthy of testing in the context of a beta site.

You might find the clickable version less overwhelming.
Thanks!

Install IPFS 🆕

Overview

  • What is IPFS?
  • How IPFS Works
  • Usage ideas/examples 🆕
  • Glossary 🆕
  • FAQ 🆕

Concepts

  • Content-addressed file storage
    • Content addressing and CIDs
    • Immutability 🆕
    • Cryptographic hashing
    • Persistence (pinning)
  • Peer-to-peer file sharing 🆕
  • Merkle-DAGs
  • The IPLD data model 🆕
  • IPNS
  • libp2p
  • Bitswap 🆕
  • File systems
    • Mutable File System (MFS)
    • UnixFS
  • Integration with the existing Web 🆕
    • IPFS Gateway
    • DNSLink

How-tos

  • Customize your IPFS install
    • Configure a node
    • Modify the peers list
    • Customize an ipfs repo (js-ipfs)⬈
  • Manage files
    • Spawn a node and add a file to IPFS (js-ipfs)⬈
    • Deal with blocks
    • Pin files
    • Troubleshoot file transfers ⬈
    • Snapshots
    • Host a Git-style repo
    • Store and play videos
    • Resolve through IPLD graphs (js-ipfs) ⬈
    • Replicate large datasets ⬈
  • Work with peers
    • Observing peers
    • Circuit relay (js-ipfs) ⬈
    • Customize libp2p bundles (js-ipfs) ⬈
  • Host a website on IPFS
  • Explore the Ethereum blockchain with IPFS (js-ipfs) ⬈
  • Develop apps on IPFS
    • Making Your Own IPFS Service (basic egs)
    • Developing Apps with the IPFS API ⬈
    • Solving distributed networking problems with libp2p ⬈
    • Addressing in browsers ⬈
  • IPFS in the browser: js-ipfs
    • Build a tiny browser app to exchange files between nodes ⬈
    • Build an application with IPFS PubSub Room 📹 ⬈
    • Build a collaborative editing application using CRDT 📹 ⬈
    • Stream video using ReadableStreams ⬈
    • Implementation tools
      • Browserify ⬈
      • Parcel.js ⬈
      • Vue ⬈
      • WebPack ⬈
      • With a <script> tag ⬈
      • Electron ⬈
    • The Mutable File System in the browser (js-ipfs) ⬈
    • Using streams to add directories to ipfs in the browser (js-ipfs) ⬈
  • Interactive tutorials ⬈

API

  • HTTP API dictionary (this may need to be separated by go and js)
  • go-ipfs
    • Working with go-IPFS
    • api dictionary
    • core options API dictionary
    • coreiface API dictionary
    • core API dictionary
  • js-ipfs
    • Working with IPFS in JS
    • JS core API dictionary ⬈
    • js-ipfs-api dictionary ⬈

CLI commands (this may need to be separated by go and js)

Support & community

  • Forums ⬈
  • IRC
  • Community calls (& cal)
  • Meetups
  • ProtoSchool chapters
  • Community projects: Awesome IPFS ⬈
  • Contribute to IPFS
  • Code of conduct ⬈
  • Project & roadmap
    • IPFS specifications ⬈
    • History of the IPFS project 🆕 ⬈ (note: link to original whitepaper; this history wants to live on main ipfs.io, not docs site)
    • Implementation status (note: this may roll into the "install IPFS" section above) 🆕 ⬈
    • Roadmap ⬈
    • Research ⬈ (note: this links to main research repo, not ipfs/notes) 🆕
    • IPFS team planning/management repo ⬈

Related projects

  • MFS ⬈
  • IPNS ⬈
  • IPLD ⬈
  • libp2p ⬈
  • IPFS Cluster ⬈
  • DNSLink ⬈
  • Multiformats ⬈
  • ProtoSchool ⬈

Footer

  • Blog ⬈
  • YouTube ⬈
  • Twitter ⬈
  • Protocol Labs ⬈

jessicaschilling added a commit that referenced this issue Oct 2, 2019
@jessicaschilling
Update config.toml
a82c770 
Added link to basic gateway guide as found by @daviddias in ipfs/kubo#6694 (comment) -- understood this is a bit of a temporary band-aid, as gateway topics are covered in #273, but better than not having it in current docs site at all.
@jessicaschilling jessicaschilling mentioned this issue Oct 2, 2019
Merged
@jessicaschilling jessicaschilling changed the title Beta nav structure: test, implement Test and implement beta nav structure IA Oct 4, 2019
@jessicaschilling jessicaschilling mentioned this issue Oct 4, 2019
Closed
@ericronne
Copy link
Contributor

ericronne commented Oct 7, 2019 •
edited
Loading

Here's the latest revision. Super curious to hear thoughts from all corners! 🙏

https://workflowy.com/#/b20459dfa378

@jessicaschilling
Copy link
Contributor Author

@ericronne I think that's a submenu. What's the link for the full menu?

@ericronne
Copy link
Contributor

fixed 🔨

@jessicaschilling
Copy link
Contributor Author

@ericronne I moved the "with a script tag" example to the top of the in-browser examples, since it's the most basic, but everything looks good overall. I think we'll gain more at this point by shipping it in the beta and testing than we will iterating over it in list form.

One caveat: We should probably huddle on getting the text tweaked for consistency, clarity etc. Maybe let's just do that in our in-person next week? I suspect it'll involve a ton of back-and-forth. 😉

@ericronne
Copy link
Contributor

For any without a workflowy account, the full structure is laid out in a doc as well …
Docs IA in outline form

@ericronne ericronne mentioned this issue Oct 10, 2019
Closed
@jessicaschilling
Copy link
Contributor Author

After yesterday's Boulder user testing sessions, @ericronne and I iterated on this for a while in conjunction with @cwaring's depth-of-nav concerns. It got hard to effectively visualize in situ, so I stubbed it out in a VuePress boilerplate site. See https://github.com/jessicaschilling/ipfs-docs-vuepress-nav ... a few notes:

  • We'll need to discuss the landing pages that get reached by the top-bar nav
  • All external links just go to ipfs.io, because I ran short on time

@ericronne -- let's work together on getting this structure pinned down.
@cwaring -- when we're settled on the nav structure in this repo, can the content be moved into your working VuePress install without causing you/us too much grief?

Thanks!

@jessicaschilling
Copy link
Contributor Author

Also, note: Lots of good insights on the nav structure IA were gathered as part of IPFS Colorado in-person user testing! See #355 for details on this. @ericronne and I are incorporating those edits into the dummy VuePress repo ... watch this space.

@jessicaschilling jessicaschilling mentioned this issue Oct 19, 2019
Closed
@jessicaschilling
Copy link
Contributor Author

I've made changes to the dummy VuePress repo (https://github.com/jessicaschilling/ipfs-docs-vuepress-nav) that reflect all the items @cwaring, @ericronne and I discussed today.

@ericronne -- can you please pull down the latest edits and review with an aim to our feeling confident enough to use this as a starting point by the middle of the week?
@cwaring -- can you please have a quick look at the latest edits to make sure there isn't anything major we need to address before flowing it into the real repo later in the week?

Thank you!

@ericronne
Copy link
Contributor

Sorry for the hiccup here, but i wanted to see an option with everything in the left nav, for a side-by-side(bar) comparison before we move on to implementation. So i mocked it up.

Invision prototype of left-nav option

This opens up the top horizontal strip for utility links, etc. As with your demo site, @jessicaschilling, subsection headers wouldn't be clickable. So we only have two levels of navigable depth. I think each approach has its merits.

Thanks for indulging me! Discuss! 📣

@cwaring
Copy link
Collaborator

cwaring commented Oct 22, 2019

Either path will work but wherever possible I will always lean towards simplifying the structure and overall I still prefer a single navigation hierarchy.

My main concern was the level of depth going beyond 3 tiers, things start to become awkward to present elegantly at this point. So if we can balance the depth of the nested topics, either by removing grouping pages, using concise titles and handling in-page header navigation differently, then we might have the best of both options.

The key for me is to be consistent so our constraints are clear and don't end up mixing navigation metaphors :)

@jessicaschilling
Copy link
Contributor Author

Thanks for mocking this up, @ericronne ... my only concern would be that exposing H2 subtopics (which is useful) in the nav gives you another layer of depth, which starts looking awkward (see below).

Two other considerations that are making me lean toward the top nav, even though I'm personally not a fan of them in general:

  • We had a few user testing folks comment on the topical/semantic distinction between the highest-level nav items (particularly concepts vs how-tos) in a way that separating these out into "chapters" via the top nav could be particularly effective
  • At mobile widths, those top nav items end up in the left nav anyway

subtopics

@ericronne
Copy link
Contributor

The left-nav motif could serve to keep us in check re nav-structure depth.
It's a judgement call, tho; good examples exist in both arrangements.

Some left-nav egs from our spreadsheet …
Twitter
Dat
Gitbook (with deeper menu, not very elegant imo)
Angular
Hugo

If the nav ends up in a left-nav-esque format on mobile, then it seems more consistent to go with the left nav on desktop, to me.

Pros Cons
Split nav Chapter-like feel Two separate navigation areas
Structural flexibility
Left nav All options in one place Structural limitation
Top area freed for utilities (search, language, etc), other navigation

Shall i set up a hangout tomorrow for us to make the call?

@ericronne
Copy link
Contributor

ericronne commented Oct 22, 2019 •
edited
Loading

And now back to our regularly scheduled program: "Discussing the Actual Navigational Structure"

Some thoughts on labeling and categorization …

  • Install IPFS
    • Testing showed that users expect installation to be very streamlined/straightforward. A single, uncluttered page is probably wise.
    • @olizilla has advised us to point users to Desktop installation as the default (not just for toe dippers), so i'll wireframe with this as the hero.
    • I'll use subheads along the lines of the four sub-pages in @jessicaschilling's demo to categorize the various implementation options
      Concepts
    • I wouldn't fall on my sword here, but topics such as "What is IPFS?" don't strike me as "concepts" so much as background material/introduction. The word "Basics" feels broader.
    • Testing surfaced that a glossary link might not fit here. Individual words could be underlined (perhaps with a dotted rule), and the full glossary accessible from a utility area (maybe in the upper-right, by search, if we go with the left-nav motif ;) )
    • (FAQs might not be ideal here, either, but testing didn't seem to surface that as an issue.)
  • How-tos
    • Coolio
  • API & CLI
    • Goot
  • Support (full title: Support & community)
    • This is a tough one. Most of the topics here don't feel like support to me. If i clicked "support," i would expect to see contact info. This kind of strikes me as handing off the problem to someone else, but i don't have a great alt suggestion. Community seems more fitting on the whole, but not spot on either. "Ecosystem"? Shruggie.

@jessicaschilling
Copy link
Contributor Author

@ericronne @cwaring No need to discuss. I'll go back through the VuePress dummy and adjust everything to remove the top nav. Will also incorporate your edits from above.

@jessicaschilling
Copy link
Contributor Author

Oh - and re the glossary thing - I'll leave a glossary page in the nav for now (curious to see what response we do/don't get to its "nothing to see here" page) but I did add inline glossary hover text to the features voting (see #319)'s Canny page: https://ipfs.canny.io/admin/board/docs-features

@jessicaschilling
Copy link
Contributor Author

jessicaschilling commented Oct 23, 2019 •
edited
Loading

@cwaring @ericronne:

I believe the IA itself is good to go, but we will need to address some issues that are beyond my VuePress ken. These are related to the fact that "Install" and "Support & community" are single-page menus and don't have submenus in them. As a result,

  • Clicking on "Basics" and then clicking on "Install" leaves the "Basics" menu open
  • H2s for "Install" appear the same size-wise as, say, "Basics"/"IPFS in a nutshell" -- in other words, the visual hierarchy isn't consistent

I'm not sure if the best way to remedy this is by customizing the sidebar nav in our own theme, or if we need to nest pages in the "Install" and "Support & community" sections to make them arbitrarily (not semantically) consistent. I'd rather not do the latter, because it forces us into a weird situation in "Install" where the three H2 use cases for different IPFS installs would have to be on separate pages (yuck). @cwaring, can you please advise? Thank you!

@jessicaschilling
Copy link
Contributor Author

Further edits to reconcile nav structure are here:
https://ipfs-docs-navtest.netlify.com/install/
@cwaring @ericronne -- please have a look to see if this addresses the last round of comments.

jessicaschilling added a commit to ipfs/ipfs-docs that referenced this issue Oct 24, 2019
@jessicaschilling
Added files and nav
9c5af69 
- Added files from dummy playground repo
- Updated left nav with dummy-playground IA
- NOTE! Commented out `sidebar: 'auto'` in locales for English

Closes ipfs-inactive/docs#273
@jessicaschilling jessicaschilling mentioned this issue Oct 24, 2019
Merged
@jessicaschilling
Copy link
Contributor Author

Great discussion with @cwaring and @ericronne to clean up some loose ends. Just moved everything that we'd built in the dummy repo over to the docs beta repo -- once ipfs/ipfs-docs#2 is merged the changes will be visible here.

We'll want to pay close attention to the nav in the initial round of docs beta testing, of course, but until then: Closing this issue!

@jessicaschilling jessicaschilling mentioned this issue Dec 4, 2019
Closed
@jessicaschilling jessicaschilling mentioned this issue Jan 6, 2020
Closed
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees

@cwaring cwaring

@jessicaschilling jessicaschilling

@ericronne ericronne

Labels
dif/medium Prior experience is likely helpful effort/weeks Estimated to take multiple weeks topic/design-ux UX strategy, research, not solely visual design
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Added files and nav ipfs/ipfs-docs
3 participants
@cwaring @jessicaschilling @ericronne