particle-iot / particle-iot/docs
Improve links between examples and docs
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:
- The example pointed to http://docs.particle.io/photon/firmware/#spark-function which does redirect to https://docs.particle.io/reference/firmware/photon/ but is missing #particle-function- so as a beginner user I'm left wondering what I'm supposed to be looking at.
- This could be a short URL e.g. http://docs.particle.io/button-function which would have redirected to the original URL
- After doing the major revision of the docs, you'd know that anything starting with
http://docs.particle.io/photon/firmwarehad moved, and "spark" was renamed to "particle", so you could search through the list of URL redirects and update all the links at once without needing to search through all the examples and update individually (which probably wouldn't happen anyway) - The URL redirect would now point to https://docs.particle.io/reference/firmware/photon/#particle-function-
- Your users are happy
- Profit
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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