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

Group API docs by purpose instead of collection #3404

Closed
justinbmeyer opened this Issue Jul 7, 2017 · 5 comments

Comments

Projects
None yet
6 participants
@justinbmeyer
Copy link
Contributor

justinbmeyer commented Jul 7, 2017

tldr; Our packages should be grouped by purpose instead of by collection. This proposes to reorganize the documentation and give new users a more simplified understanding of CanJS.

This was discussed at a contributors meeting (8:30)

The Problem

The API docs sidebar looks like:

canjs_-_api_docs

There are two problems with the API docs:

  • It's huge and intimidating to new users
  • It's primarily organized around collection (quality and likelyhood of use) instead of purpose.

Intimidating new users

Listing 60 packages makes CanJS seem way too big. Most of these packages they will never have to use, or use very rarely.

Organized by collections instead of purpose

While being organized by collection is useful at focusing people's attention on what they will primarily use, it does little to inform people what a given package actually does.

Solution

I would like to group our packages by purpose while still retaining the ability to "focus" new users on the APIs that they need to know.

The following is a rough idea of what the sidebar might look like to a new user:

untitled

The [C], [I], [E], and [L] buttons toggle if core, infrastructure, ecosystem, or legacy packages should be shown. If someone toggled the buttons, in this case the[I] button, they would see the infrastructure packages, likely color-coded:

untitled

The following shows most of CanJS's packages organized this way:

  • Observables

    • can-compute I
    • can-define C
    • can-event I
    • can-observation I
    • can-simple-map I
    • can-stream E
    • can-stream-kefir E
    • can-define-stream E
    • can-define-stream-kefir E
  • Views

    • can-component C
    • can-stache C
    • can-stache-bindings C
    • can-view-callbacks I
    • can-view-live I
    • can-view-model I
    • can-view-nodelist I
    • can-view-parser I
    • can-view-scope I
    • can-view-target I
    • can-react-component E
    • react-view-model E
    • react-view-model/component E
    • can-stache-converters E
  • Data Modeling

    • can-connect C
    • can-set C
    • can-connect-cloneable E
    • can-connect-feathers E
    • can-connect-ndjson E
    • can-connect-signalr E
    • can-fixture E
    • can-fixture-socket E
    • can-ndjson-stream E
  • DOM Utilities

    • can-control I
    • can-dom-events I
    • can-event-dom-enter I
    • can-event-dom-radiochange I
    • can-jquery
  • Routing

    • can-route C
    • can-route-pushstate C
    • can-param I
    • can-deparam I
    • can-stache/helpers/route
  • Typed Data

    • can-construct I
    • can-construct-super E
    • can-cid I
    • can-namespace I
    • can-reflect I
  • Polyfills

    • can-symbol I
    • can-vdom
  • JS Utilities

    • can-ajax
    • ...

Implementation Details

Design

  • If someone clicks directly a link like "can-map", the API Docs should only show modules in their collection.
  • If multiple collections are shown at once, we should sort packages first by collection, then by name.
  • Collection icons should be color coded to show how "safe" a collection's tools are.

Development

  • We will probably need some form of the sidebar's data (or a reduced docMap) provided to the client.
  • I think we should implement this entirely in client-js first, then maybe make pages get generated with the sidebar.

Tasks

  • - Get a design
  • - Change every package to have a "purpose" group and tag it with its collection.
  • - Make the sidebar able to load at least the packages graph. Possibly have the sidebar completely generated in the client.

Concerns

  • Having the collection toggle at the top might be annoying because you wont be able to see what's there.
  • Do we hide groupings that aren't present?
  • If we remove most helpers to another project #3426 how does that change things?
@matthewp

This comment has been minimized.

Copy link
Contributor

matthewp commented Jul 7, 2017

:+1 I like it

@justinbmeyer justinbmeyer changed the title Group API docs by capability instead of collection Group API docs by purpose instead of collection Sep 18, 2017

@justinbmeyer

This comment has been minimized.

Copy link
Contributor Author

justinbmeyer commented Sep 18, 2017

One way to deal with the concerns that:

  • expand / collapse might be far from the area the user is viewing
  • we might hide groupings without core parts

Is to add buttons to each purpose grouping:

api_docs

Another alternative:

api_docs

@adrifolio

This comment has been minimized.

Copy link
Contributor

adrifolio commented Sep 18, 2017

Here's another idea:

1.) Show the entire name of each toggle
screen shot 2017-09-18 at 1 03 51 pm

2.) Show colored squares next to each package according to group they belong to. In the example below, ecosystem and legacy have not been selected.

screen shot 2017-09-18 at 1 02 34 pm

Note that the color for each group would needs more consideration, I just picked some random colors to show this concept.

@bmomberger-bitovi

This comment has been minimized.

Copy link
Contributor

bmomberger-bitovi commented Sep 19, 2017

@adrifolio's idea looks very nice, but please remember colorblind users. Perhaps icon bullets and an outline style for inactive?

@chasenlehara chasenlehara added the Epic label Sep 29, 2017

@canjs canjs deleted a comment from frank-dspeed Oct 10, 2017

chasenlehara added a commit to canjs/can-compute that referenced this issue Oct 30, 2017

Change this package’s collection to infrastructure
This was a chance Justin had shown in his description for canjs/canjs#3404
@chasenlehara

This comment has been minimized.

Copy link
Member

chasenlehara commented Nov 3, 2017

This is finished and has been deployed to https://canjs.com

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.