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

Improve the content of the CanJS documentation #4116

Open
chasenlehara opened this Issue Apr 20, 2018 · 2 comments

Comments

Projects
None yet
5 participants
@chasenlehara
Member

chasenlehara commented Apr 20, 2018

TLDR: we propose reviewing our current docs to look for:

  • pages that don’t have useful content
  • broken links
  • bad/broken code examples & demos
  • other ways we can improve them to make them more useful

This was discussed on a recent live stream (8:49).

Problem

Our docs have evolved over the years without a thorough review. Inevitably, some docs have deteriorated with broken links, out-of-date examples, and busted demos. Some pages lack good content or examples.

Solution

Review the most popular pages (maybe top 50?) to:

  • Fix broken links, code examples, demos, etc.
  • Look for ways to improve the content

Additionally, we should tackle these existing issues:

We should also look at issues with the “documentation” label.

As a stretch goal, we should consider:

Steps

  1. Check for documentation tags in your project's issues. Address these.
  2. Check for broken demos, links, spelling or other obvious issues. For spelling, you can copy/paste text into word or something with spell check.
  3. Read for clarity. Make sure modern techniques are being used. Fix any obvious mistakes.
  4. Use ES6 import syntax instead of CJS in sample code. Add @codepen where relevant.
  5. Create an issue detailing any further improvements. Discuss if we should do any of these while working on this project.

Packages

Priority Guides

Core

  • can-define
  • can-query-logic (3)
  • can-fixture (3)
  • can-value (2)
  • can-stache (2) - (5)
  • can-stache-bindings (2)
  • can-component (3)
  • can-rest-model (Mike)
  • can-realtime-rest-model (Mike)
  • can-route (Kevin)
  • can-route-pushstate (Kevin)
  • can-stache-route-helpers (Kevin) - done, but needs codepens for demos

Secondary Guides

  • Forms (Kevin)
  • Chat
  • TodoMVC
  • ATM

Unsorted

  • can-stache-converters
  • can-connect
  • can-debug
  • can-ajax
  • can-memory-store
  • can-observe
  • can-reflect
  • can-super-model
  • can-assign
  • can-attribute-encoder
  • can-attribute-observable
  • can-bind
  • can-child-nodes
  • can-cid
  • can-compute
  • can-connect-feathers
  • can-connect-tag
  • can-construct
  • can-construct-super
  • can-control
  • can-data-types
  • can-define-backup
  • can-define-lazy-value
  • can-define-stream
  • can-define-stream-kefir
  • can-define-validate-validatejs
  • can-deparam
  • can-diff
  • can-dom-data
  • can-dom-data-state
  • can-dom-events
  • can-dom-mutate
  • can-event-dom-enter
  • can-event-dom-radiochange
  • can-event-queue
  • can-fixture
  • can-fixture-socket
  • can-fragment
  • can-globals
  • can-kefir
  • can-key
  • can-key-tree
  • can-list
  • can-local-store
  • can-log
  • can-make-map
  • can-map
  • can-map-define
  • can-namespace
  • can-ndjson-stream
  • can-observation
  • can-observation-recorder
  • can-param
  • can-parse-uri
  • can-queues
  • can-reflect-dependencies
  • can-reflect-promise
  • can-route-hash
  • can-route-mock
  • can-route-pushstate
  • can-set-legacy
  • can-simple-dom
  • can-simple-map
  • can-simple-observable
  • can-stache-key
  • can-stream
  • can-stream-kefir
  • can-string
  • can-string-to-any
  • can-symbol
  • can-validate
  • can-validate-interface
  • can-validate-legacy
  • can-validate-validatejs
  • can-vdom
  • can-view-autorender
  • can-view-callbacks
  • can-view-live
  • can-view-model
  • can-view-nodelist
  • can-view-parser
  • can-view-scope
  • can-view-target
@nlundquist

This comment has been minimized.

Collaborator

nlundquist commented May 1, 2018

I'd love if as part of this effort we modify bit-docs / documentjs to warn about broken links (and add a strict mode flag that would return a failed exit code if broken links were found)

@chasenlehara chasenlehara added the Epic label May 23, 2018

@justinbmeyer justinbmeyer referenced this issue Jun 7, 2018

Closed

CanJS 5.0 #3854

5 of 13 tasks complete
@chasenlehara

This comment has been minimized.

Member

chasenlehara commented Jun 29, 2018

This isn’t something we have to address as part of tackling this proposal, but where we’re already updating code… @CODE-REaD brings up a good point that more distinctive variable & property names can make it easier to understand code examples: https://forums.donejs.com/t/generic-property-names-confuse-the-beginner/908

Aosanders pushed a commit that referenced this issue Jul 12, 2018

phillipskevin added a commit that referenced this issue Jul 16, 2018

Merge pull request #4317 from canjs/var-let-const
Replaces var with let/const in the canjs/docs files. Fixes #3846 & addresses #4116

@justinbmeyer justinbmeyer referenced this issue Aug 30, 2018

Merged

codepen last demo #4442

0 of 1 task complete

@phillipskevin phillipskevin referenced this issue Oct 10, 2018

Open

Clean up documentation #301

0 of 7 tasks complete
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment