[EPIC] v3.0 Docs IA redesign

[shannonbux]

Epic Template

Who will own this?

What Area of Responsibility does this fall into? Who will own the work, and who needs to be aware of the work?

Area of Responsibility:

Select the Area of Responsibility most impacted by this Epic

• Community

• Learning

• Gatsby Core

• Enterprise

• Design

• Marketing

• Company/Admin

• Sales

  AoR owner	@shannonbux
  Domain owner	@name
  Project manager	@name
  Tech lead	@name
  Contributors	@name

Summary

This epic organizes enhancements to the docs that will make it easier to flow on ideal pathways through the docs.

How will this impact Gatsby?

Domains

List the impacted domains here

Components

List the impacted Components here

Goals

What are the top 3 goals you want to accomplish with this epic? All goals should be specific, measurable, actionable, realistic, and timebound.

How will we know this epic is a success?

What changes must we see, or what must be created for us to know the project was a success. How will we know when the project is done? How will we measure success?

User Can Statement

• User can...

Metrics to Measure Success

• We will see an increase /decrease in...

Additional Description

Phase 3:

• API on top level nav
• versions of the docs
• Way to test APIs. Ask devs for their favorite ones.
• automatically pull in doc prereqs at top of each page (see https://www.cockroachlabs.com/docs/stable/transactions.html as a great example of how to design this. Not sure how to code it)
• doc accessibility/design options (changing font type and size or screen and font colors, what about language?), toggle sidebar to disappear, reappear
• searchable API reference
• track one ideal "paths" through the docs to see if idea is worth expanding
• a breadcrumb trail (like Amazon does)
• suggesting "next steps" at the bottom of docs
• dedicated search page
• Featured docs

Ideas from usability testing:

• create issue to solve problem of split-attention learning (which involves attention being pulled to multiple screens)
• Stub articles - how to be notified when it's done?
• Would be nice to know where Gatsby came from (origin story) like in Vue.js article: https://vuejs.org/v2/guide/comparison.html

Add to style guide and go through with fine-toothed comb:

• Consistency with semicolons in code examples and colons (or periods) before code examples
• Consistency with capitalization of programming languages
• take out "simple" "easy" etc. and "difficult" wording (refer to Github issue on this)
• Consistent headers

MVP

#6899

Phase 2

#6900

RFC

gatsbyjs/rfcs#5

What are the risks to the epic?

In a few sentences, describe what high-level questions we still need to answer about the project. How could this go wrong? What are the trade-offs? Do we need to close a door to go through this one?

What questions do we still need to answer, or what resources do we need?

Is there research to be done? Are there things we don’t know? Are there documents we need access to? Is there contact info we need? Add those questions as bullet points here.

How will we complete the epic?

What are the steps involved in taking this from idea through to reality?

How else could we accomplish the same goal?

Are there other ways to accomplish the goals you listed above? How else could we do the same thing?

[jsjoeio]

Some things I wanted to share as well!

https://nextjs.org/learn/ - Next.js has this cool tutorial with questions at the end of each section. Could be cool for future Gatsby tutorials!
https://www.twilio.com/quest/welcome - TwilioQuest - "TwilioQuest is an interactive, self-paced game where you learn how to Twilio." used this to learn how to use Twilio! Also another fun thing to consider for future Gatsby tutorials.

[shannonbux]

Great search page design: algolia.com/doc (thanks @cdock1029 for this idea)

[fk]

💯agreed on the algolia reference! I'd like to think that we're a tiny step closer to something comparable with the "landing page" approach shown in #7544 (comment)?
Even if I'm not very far into the design of that page, I'd love to hear your thoughts over there @shannonbux and everyone!

[gatsbot]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.

If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!

Thanks for being a part of the Gatsby community! 💪💜

[gatsbot]

Hey again!

It’s been 30 days since anything happened on this issue, so our friendly neighborhood robot (that’s me!) is going to close it.

Please keep in mind that I’m only a robot, so if I’ve closed this issue in error, I’m HUMAN_EMOTION_SORRY. Please feel free to reopen this issue or create a new one if you need anything else.

Thanks again for being part of the Gatsby community!