particle-iot / particle-iot/docs

Improve links between examples and docs

Open
#235 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
148
Forks
266
Avg merge
14h 41m
Merged PRs (30d)
16

Description

I'm going through docs from the perspective of a beginner Photon user (I'm writing some tutorials) and have so far found two broken links in example code and submitted pull requests. There's got to be a less fragile way of putting links to documentation in the examples.

Here's an idea: don't use full URLs in the examples, but short URLs that redirect to the actual docs URL (e.g. what you already do with http://particle.io/buttonstart). Keep a list of the all the redirects. If you're doing a major change that would change a URL for a piece of documentation, you can search the list and update the redirects all at once without touching the example code.

Example from the PR I just submitted for an Internet Button example:

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the linked Internet Button pull request and the existing particle.io/buttonstart redirect pattern. Determine where redirects are maintained and how documentation URLs are updated; done means examples can use stable short links, redirects point to the current documentation sections, and the redirect list is maintained.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.