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.

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

Reorganize the API page by topic #76

Closed
matthewp opened this Issue Sep 22, 2017 · 2 comments

Comments

Projects
None yet
1 participant
@matthewp
Copy link
Member

commented Sep 22, 2017

tldr; Our API docs should be grouped by the common topics that people need help with. This proposal seeks to update the API page to make the important topics stand out.

This was discussed at a contributors meeting (58:12)

The Problem

The API docs page looks like this:

screen shot 2017-09-22 at 7 05 14 am

And this isn't even all of it! The problems are:

  • Guides and Topics are really kind of the same thing. In this case guides are step-by-step instructions, but there is little overlap, so it doesn't make sense to separate them.
  • Common things people care about are missing, like live-reload.

Solution

I would like to group our docs by the topic they are associated with. This will make it easier for users to find exactly what they are looking for.

It might look like this:

  • Development
    • Getting Started
    • Progressive Loading
    • Development Bundles
    • Using NPM Packages
    • Hot Module Swapping
    • Configuration
    • Shimming
    • Conditional Loading
    • Using Babel
    • Circular Dependencies
  • Bundling
    • Optimized Builds
    • Tree Shaking
    • Code Splitting
    • Multi-main Builds
    • Project Exporting
  • Production
    • Loading Scripts from a CDN
    • Bundle Manifests
  • Advanced
    • Writing Plugins
    • Writing Extensions

Implementation

Design

Each link to these topics should take the user to a portal. The portal is a place to:

  • Learn from a high level what the topic is about and how Steal helps.
  • Link to API documentation (steal and steal-tools, even ecosystem packages).
  • Link to any step-by-step guides.

Tasks

  • - Finalize the list of topics.
  • - Move existing topics out of steal/steal-tools and into stealjs repo.
  • - Create new groupings for Development, Bundling, Advanced.
  • - Write new docs that we don't currently have.
@matthewp

This comment has been minimized.

Copy link
Member Author

commented Oct 11, 2017

WIP

  • Development
    • - Getting Started
    • - Progressive Loading
    • - Development Bundles
    • - Using NPM Packages
    • - Hot Module Swapping
    • - Configuration
    • - Shimming (deferring)
    • - Conditional Loading
    • - Using Babel
    • - Circular Dependencies
  • Bundling
    • - Optimized Builds
    • - Code Splitting
    • - Multi-main Builds
    • - Project Exporting
  • Production
    • - Loading Scripts from a CDN
    • - Bundle Manifests
  • Advanced
    • - Writing Plugins
    • - Writing Extensions (deferring)

@matthewp matthewp self-assigned this Nov 8, 2017

matthewp added a commit that referenced this issue Nov 8, 2017

matthewp added a commit that referenced this issue Nov 8, 2017

Add the Using npm Packages topic
This adds the topic page, __Using npm Packages__ that organizes
information on installing/using packages found on npm. Part of #76

matthewp added a commit to stealjs/steal-tools that referenced this issue Nov 14, 2017

Remove guides from this repository
Removing guides from this repository and moving them into
stealjs/stealjs. Part of stealjs/stealjs#76

matthewp added a commit to stealjs/steal-tools that referenced this issue Nov 14, 2017

Remove guides from this repository
Removing guides from this repository and moving them into
stealjs/stealjs. Part of stealjs/stealjs#76
@matthewp

This comment has been minimized.

Copy link
Member Author

commented Nov 16, 2017

Done!

@matthewp matthewp closed this Nov 16, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.