---
# System prepended metadata

title: Documentation Infrastructure Phase 2

---

# Documentation Infrastructure Phase 2

## Desired outcome
Documentation Section of developer.tbd.website evolves to:
* Quickly get developers:
  * To their area of interest
  * Building tangible applications that provide value to them 
* Promote use case -driven development
* Introduce new Documentation Content Types intentionally not addressed in Phase 1.
  * Described below
* Include clear, documented pathways for core developers and contributors to submit further documentation types and use cases.
* Have all structure neccesary for a Deep Dive with Core engineers on content for Getting Started, starting 6 March.

Principles:
* Centered around use cases and value to developers
* Scoped to the Documentation Section of the Developer Site 

Non-goals:
* Concept education and supporting media exists elsewhere on developers.tbd.website. Link as appropriate to build a cohesive experience across the Developer Site.
* Fulfill the entire [Getting Started Experience](https://github.com/TBD54566975/collaboration/issues/48). This is a critical component of that Experience.
* High-fidelity UX and Design. This should tee up the necessary wireframes to have that work done in a Phase 3.

Scheduling: 
* Timeboxed
* Phase 2 Start: Wednesday, 15 February 
* Phase 2 End: Friday, 3 March

## Gap Analysis

### We currently have:
* Phase 1 Documentation Section
  * Everything we need to advance Docs Section structure and content authoring
* API Docs section
* Tutorials section
* Getting Started stub
* Labs as repositories from OSE

### We need:

* Revised Information Architecture - how we're organizing our info
  * Tangibly: a Site Map for the Documentation Section of developer.tbd.website 
* Revised "Docs Home": Proposed as "Getting Started" below
  *  Map of the Web5 Platform and its components
  *  List of Featured Guides, the use cases we're promoting
* [Project Documentation](https://github.com/TBD54566975/collaboration/issues/38) Section
* Sample Applications Section and Store/Repo
  * Separate from OSE Labs work; where prototypes move for longer-term maintenance and higher-fidelity design and documentation
* Playground Applications Section and Store/Repo
  *  Separate from OSE Labs work; where prototypes move for longer-term maintenance and higher-fidelity design and documentation
* Web development tasks to implement new designs

## Documentation Content Types
These are the content types which comprise our documentation. 

These types are distinct from how the information is organized in the Site Map.

* **Getting Started Home**
  * Docs Home; the entry point to quickly understanding Web5's value and moving developers to tangibly get started through one of the Guides or other Documentation Types
* **Guides**
  * Hub for a Use Case
  * Links to other Documentation Content Types which together describe the Use Case or supplement with additional relevant information
  * _ALR: The term "Guide" confuses me because it seems close to "Tutorial". Is a "Tutorial" not a step-by-step Guide? Are there terms we might consider that are more intuitive? Or is there a fun way we can refer to these action-driven sections, like "Missions" or "Quests"?_
* **Tutorials**
  * A step-by-step set of instructions for fulfilling a use case. 
  * Clearly outlines "if a developer invests X time, by the end they'll have a working Y" 
  * _Define common structure for these_
* **Sample Applications**
  * A standalone piece of code that can be built and run. Shows a use case, feature, or a combination of these together to accomplish a task. 
  * Has both:
    * Code as a repository or folder in a repository (to be built and run)
    * A URL to where we've deployed this for folks to play
      * _^ Is that true?_
  * Examples:
    * Yeeter
    * Notes app 
  * Maintenance requirements
    * CI enforcing these can:
      * Build
      * Be deployed
      * Pass tests proving they work as intended 
  * _Define common structure for these_
    * Link to repo to pull and run on your own?
    * Instructions for running the sample application?
    * Cross-linking to the concept(s) the sample application employs as Tutorials?
* **API Docs**
  * Language- or framework-native listing of the API and its use. Typically covers method/function names, inupts, outputs, and exceptional cases.
  * Listed [here](https://developer.tbd.website/docs/api/) by component.
  * _The Big Question to solve w/ OSE_
    * Web5 is the Platform. Developers code to its application model and get data messaging, storage, privacy, credentials, etc for free. So: _What is the Web5 API?_
  * Component Examples:
    * HTTP APIs, inlined into Developer Site:
      * [SSI Service](https://developer.tbd.website/docs/apis/ssi-service)   
    * Go API
      * [SSI SDK](https://pkg.go.dev/github.com/TBD54566975/ssi-sdk)
    * JS/TypeScript API
      * [DWN JavaScript SDK](https://tbd54566975.github.io/dwn-sdk-js/)  
* **Playgrounds**
  * Web applications which let the user see code and change it, watching how the outputs respond to those changes
  * _Define common structure for these_
    * Link to live hosted playground?
    * Link to repo to pull and run on your own? 
    * Instructions to build?
  * Examples
    * [Verifiable Credentials](https://tbd54566975.github.io/web5-components/demo/VerifiableCredential/) 

## Proposed Information Architecture
An outline view of how information should be organized. Informs the wireframes, navigation, and content sections.

  * **Getting Started Home**
    * _Purpose_: The Web5 Platform, its purpose and value, and the components in it. User chooses their "Getting Started" Experience: ie. Web5 messaging and data storage, Credential issuance, Creating their identity on the decentralized web (DID)   
  * **Guides**
    * The "hub" for each use case
      * Examples of Guides:
        * Creating Your Identity on the Decentralized Web
        * Sending and Receiving Decentralized Messages
        * Issuing a Credential
      * Contains:
        * Tutorials
        * Sample Applications
        * Playground (if appropriate)
        * Projects used (links to Projects pages)
        * ...others from "Documentation Content Types"
* Projects
  * Open format in MDX or Markdown for Project Leads to surface project information on the Developer Site.  
  * One per top-level project, for example:
    * SSI
    * DWN
    * Wallet
    * tbDEX
    * Web5
  * Shows the components which make up a Project
      * Example for SSI:
        * ssi-service
        * ssi-sdk
      * Example for Web5:
        * Web5 API  
* Documentation Content Types
  * Additionally let the developer explore by Documentation Type as a list, rather than only by use case **Guides**?
      * **Tutorials**
      * **Sample Applications**
      * **Playgrounds**  

## Proposed Work items to break off into Issues
* Information Architecture - how is information organized and presented?
* UX and Wireframe
  * From Bobbilee's base work in Figma. Incorporates decisions made in the "Information Architecture" task
  * Evolve Figma doc to incoporate decisions we make here. Practically-speaking, how is that done?
  * Potential handoff point to high-fidelity design phase 
* Site Development
  * Inventory of new components that need to be created
  * Moving from pure Markdown publishing to MDX
  * Guide to content authors documenting the above - MDX structure, components available, and how to use the components. 
* Tutorial structure
  * An author's guide for writing tutorials
  * Is there a common format all tutorials take?
  * Includes:
    * Best practices?
    * Template? 
* Sample Applications structure
  * An author's guide for writing sample applications 
  * Is there a common format all sample applications take?
* Content authoring
* Phase 3 Backlog:
  * Design tasks from UX wireframes
  * Web development to implement Designs

## Implementation Considerations
* Embed into every Project section a link to contribute - and make sure it's offshoring into appropriate homes
* Link out to FAQs and Glossary on the Dev Site where appropriate (and/or tooltip)
* Embed feedback forms where appropriate
* Pop outs to choose software version where tutorials are, or where code is embedded
* Embed media into guides where appropriate, perhaps cross-linking into where they're "housed" in Media section. Perhaps the "embed" is exandable as an option and doesn't take up lots of real estate unless user opts into.

## External Examples
* [Use Case Approach from Mattr](https://learn.mattr.global/docs/)