mozillareality / hubs-docs

Hubs Docs

This repo is for the documentation for Hubs, and related products such as Hubs Cloud and Spoke.

The documentation is under active development. If there are any changes or updates you recommend, feel free to submit a pull request or let us know in our Discord Server.

This website was created with Docusaurus.

Docusaurus information

What's In This Document

• Get Started in 5 Minutes
• Directory Structure
• Editing Content
• Adding Content
• Full Documentation

Get Started in 5 Minutes

1. Make sure all the dependencies for the website are installed:

# Navigate to the website directory
$ cd website

# Install dependencies
$ npm ci

2. Run your dev server:

# Start the site
$ npm start

Directory Structure

Your project file structure should look something like this

my-docusaurus/
  docs/
    doc-1.md
    doc-2.md
    doc-3.md
  website/
    core/
    node_modules/
    pages/
    static/
      css/
      img/
    package.json
    sidebar.json
    siteConfig.js

Editing Content

Editing an existing docs page

Edit docs by navigating to docs/ and editing the corresponding document:

docs/doc-to-be-edited.md

---
id: page-needs-edit
title: This Doc Needs To Be Edited
---

Edit me...

For more information about docs, click here

Editing an existing blog post

Edit blog posts by navigating to website/blog and editing the corresponding post:

website/blog/post-to-be-edited.md

---
id: post-needs-edit
title: This Blog Post Needs To Be Edited
---

Edit me...

For more information about blog posts, click here

Adding Content

Adding a new docs page to an existing sidebar

1. Create the doc as a new markdown file in /docs, example docs/newly-created-doc.md:

---
id: newly-created-doc
title: This Doc Needs To Be Edited
---

My new content here..

1. Refer to that doc's ID in an existing sidebar in website/sidebar.json:

// Add newly-created-doc to the Getting Started category of docs
{
  "docs": {
    "Getting Started": [
      "quick-start",
      "newly-created-doc" // new doc here
    ],
    ...
  },
  ...
}

For more information about adding new docs, click here

Full Documentation

Full documentation can be found on the website.

hubs-docs's Issues

Add Digital Ocean Quick Start Guide

The Intro to Hubs Cloud page has a link to a non-existent digital ocean quick start guide:
https://github.com/MozillaReality/hubs-docs/blob/fa00f4ee8c6d560407465dc70cedf0a855dc5890/docs/hubs-cloud-intro.md

Documentation of data regions in Hubs Cloud services

Some areas of the world have different requirements for where participant data can be stored and accessed from. We should have a document somewhere that outlines which services for Hubs Cloud are restricted to different regions, so that organizations with data storage and transmission requirements would be able to determine the viability of Hubs Cloud for specific use cases.

(Re-created from Hubs-Foundation/hubs-cloud#12)

The 500 error is displayed when clicking certain links from footer

[Affected Versions]:

• Firefox Release 82.0.3
• Chrome 87.0.4280.66

[Affected Platforms]:

• Windows 10x64

[Prerequisites]:

• The https://hubs.mozilla.com/ website is opened.

[Steps to reproduce]:

1. Click the "Docs" button from the navigation bar.
2. Scroll to the footer of the page.
3. Click the "Hubs Documentation" link.
4. Observe the behavior.

[Expected results]:

• The Hubs Documentation section is displayed.

[Actual results]:

• The 500 error is displayed or the page remains in a loading state.

[Notes]:

• This issue is also reproducible when clicking the "Spoke Documentation", For Creators", and "For Developers" links.
• In Firefox the page remains in a loading state and on Chrome the 500 error is displayed.
• I was not able to test this issue on MacOS, Linux or mobile devices.
• Attached is a screen recording of the issue:
  

Content curation guidelines document empty

In the "Room Settings" page, second paragraph, there's a "content curation guidelines" link to the page: https://hubs.mozilla.com/docs/creators-content-guidelines.html But thus page has no content.

"Supported Devices & Browsers" section and below are not displayed

"Supported Devices & Browsers" section and below are not displayed in

https://hubs.mozilla.com/docs/hubs-create-join-rooms.html

Perhaps it could be caused with this commit.

4e66228

I guess multiple lines commenting out may not work.

Guide for network admins to open ports needed for Hubs

From discussion: Hubs-Foundation/hubs#3043

How to whitelist just the servers needed for the necessary port range so network security isn't compromised.

Feedback from doc review

Add a welcome/introduction type article at the top of articles: orientate people first coming to that section, telling them what that documentation will allow them to achieve, who it is for, what it's about, etc. I'd advise putting a similar introduction type article at the top of all the sections, particularly:

Hubs Documentation - Consider "Hubs user guide" or similar since all of this documentation falls under the branch of 'Hubs Documentation'
Spoke Documentation - say what spoke is, who it is for, and what kinds of things you can do with it. What is the basic stuff people will want to try, and what are the most advanced bits to go onto later on
For Creators - May not be clear who this document is for
For Developers - Audience here may not be clear; it's also not clear if/how Hubs Cloud documentation is different than the general developer resources

Add a section about the lobby

Add disable transfer lock for registered domains into HC stack creation

In aws stack creation and troubleshooting documentation, write a blurb about disabling aws's "Transfer Lock"

Improve documentation on how to rebuild the client on AWS.

This came up on the Hubs Discussions forum so I'm recording it here for our records - Hubs-Foundation/hubs#2982

Thank you for the positive feedback! If I could throw in my bit on this, a simple document stating how to rebuild the client on AWS would go a long way for me. Thinking ahead, that would be really useful for many people. Right now, this document is not enough - its a vital subject, I get to half way the cant go forward after the prerequisites section: https://hubs.mozilla.com/docs/hubs-cloud-custom-clients.html
It would be nice to have a document stating the steps and the requirements.
Again, thank you for your interest.

Update Custom Avatar docs

From @larsbergstrom : consider updating https://hubs.mozilla.com/docs/intro-avatars.html
to include pointers to online avatar creators.

This will also include documentation for the blender add-on when it is published

Domain Recipes: clarify allowed tlds for recipe 1 and other suggestions

General Description

As a reader of the "Domain Recipes" page I would like to have more clarity as to which tlds are ok for recipe 1 in order to have 0 doubt on whether I can buy a domain on Route 53 and get started.

In more details

As I was following the quick start guide and went through the domain recipes, in particular recipe 1, I found the documentation text to be just a tiny bit unclear on the fact that ".com" and ".link" are placeholders, and can be replaced by other top-level domains (tld), say ".io" or ".co", and since this step costs money, it could/should be improved.

Small hints that overall created my doubt:

• ".link" is a very specific tld and is not necessarily a short one for what is supposed to be a short link
• There is a bit on second-level domains and their specificity
• Nowhere is it explicitly said that ".com" and ".link" are placeholders

I eventually went forward and can clarify that it is indeed perfectly ok to have a ".co" instead of ".com" for instance, while using Recipe 1.

Potential solution:

Currently, it writes:

Known bug + fix: Using a second level domain (.co.uk, .com.fr, etc)? Use Recipe 3.

Instead it could write:

".com" and ".link" can be replaced by other top-level domains at your convenience, eg. ".co", ".io" etc.
Known bug + fix: Using a second level domain (.co.uk, .com.fr, etc)? Use Recipe 3.

Aside from this, I also found:

• It was hard to guess what the short-link link does exactly. Again, the ".link" example threw me off track for a sec since it's not that short and actually longer in the example ("myhub.com" vs "myhub.link"). An illustration (screenshot), and/or a reference to the Mozilla example could be helpful ("hubs.mozilla.com" vs "hub.link")
• Someone on discord warning me that which tld to chose is also important for email server spam filters. In particular that ".space" was an issue for them
• There are leftovers from drafts/todo in the doc? For instance

mysite.com set up on on Route 53 (?)

What is the (?) doing here?

• While following Recipe 1 it was not clear when I should instantiate on a subdomain

I would be happy to submit a quick PR if someone doubles-check my language prior to it since I am not a native English speaker.

Let me know what I can clarify, in the meantime, my domains got approved, the transfer lock got disabled and my stack got successfully deployed 🎉 😄

Multilang

I'm interested in whether these docs are (or could be) multilang, and if so, how to contribute a Spanish translation to some sections.

Properly handle docs pages without the .html extension

Currently we don't rewrite the url to the correct file or even show a 404 page when the .html extension is omitted. We should fix this.

Add instructions for enabling CloudTrail

We want to encourage users to enable CloudTrail for their own auditing purposes. Some instructional documentation around that would be useful.

Add fly mode controls

The "hubs controls" page should include instructions for toggling fly mode.

Search bar not functioning (Cross post from hubs-client repo)

Hubs-Foundation/hubs#6348

Add UI Redesign landing banner to customizing look and feel page

To complement the warning banner in the admin panel.

Update instructions for Bing API key to use general purpose Cognitive Services API key

See conversation in Discord here: https://discordapp.com/channels/498741086295031808/715710114438447114/754688688243605555

And related Hubs Cloud issue: Hubs-Foundation/hubs-cloud#62

Hubs Discord Bot docs should explain the difference between bridged/bound rooms

Clarify that camera recording feature is disabled on MacOS/iOS

From: Hubs-Foundation/hubs#4040

Currently we intentionally disable camera recording feature on MacOS/iOS. But we haven't documented it anywhere.

I think we should mention it in https://hubs.mozilla.com/docs/hubs-features.html

Add Spoke Performance Guide

It'd be nice to have a guide with some basic tips on how to create a scene with good performance.

Translate Hubs Mozilla for PT-BR

I want to know the possibility of translating Hubs Mozilla to the PT-BR language so that we Brazilians can use this platform in a more friendly way to our language.

Add instructions for Mac users to enable screen-sharing via system preferences.

Mac users need to allow their browser to record the contents of their screens via their system preferences. We should add some information in the docs to indicate this.

Add Search Bar to Documentation

The code to add the search bar to the Hubs documentation site (which I believe is here: https://github.com/MozillaReality/hubs-docs/blob/master/website/siteConfig.js#L60) is present but currently commented out. When we last looked into adding the search to the site, the code worked fine for local instances of the codebase but had CSP issues when deploying to the live site.

Adding search would likely reduce the number of questions that we get through other channels, since users would have an easier time looking through the current documentation to find an answer for their issues.

Domain recipes: Make Recipe 3 vs move domain to Route 53 docs clearer

From deployment issues, it's not clear when to use Recipe 3 vs use Hosted zone when you just purchased a domain from a domain registrar like namecheap or godaddy. Update docs to reflect this.

Update readme to make the easiest contribution flow the top level item

We can improve the onboarding process for external contributors to the hubs docs site if we make the readme highlight the non-cloning path for contribution (e.g. "Click "edit" on the page you want to edit, make changes, how to add an image, submit for review as a patch)