Repository navigation
Documentation needs more explanation for in-memory url in tutorial/toh-pt6 #18869
Description
The section about the in-memory URL in the HTTP chapter of the Angular tutorial needs more detail to be clear.
The material at https://angular.io/tutorial/toh-pt6 introduces the 'api/heroes' syntax with no explanation other than the inline comment:
private heroesUrl = 'api/heroes'; // URL to web api
However, it is confusing to what api refers, and using app or apd instead works just as well. More importantly, it is unclear to what heroes refers. For example, the demo does have a heroes path in Routes and a heroes component, but heroesUrl actually refers to the heroes object used in in-memory-data-service.ts
A blog post by Brian Swartzfager's at http://www.thoughtdelimited.org/thoughts/post.cfm/learning-angular-2-tour-of-heroes-tutorial-lesson-7 makes the same point.
A StackOverflow question at https://stackoverflow.com/questions/40841523/understanding-http-in-angular-2-tutorial asks the same question and got a correct but unhelpful answer.
After locating the documentation at https://www.npmjs.com/package/angular-in-memory-web-api the syntax and its meaning became less opaque, but the Angular tutorial does not mention this. Fiddling with the live example at https://angular.io/generated/live-examples/toh-pt6/eplnkr.html was helpful, but the documentation should explain what this "URL to web api" is doing and to what heroes points.
Suggestions for improving the documentation:
- Explain the meaning of the api/heroes syntax in the documentation. The explanation of "URL to web api" is too terse to mean anything to someone who hasn't used the in-memory-web-api package. Also include a link to documentation at https://www.npmjs.com/package/angular-in-memory-web-api or some better URL.
- When constructing demos, try to avoid using the same word such as heroes for multiple different items, such as paths, files and data objects. In cases such as here where a data object is referred to with the same name as a path, it muddies the water to give 3 different things the same name, particularly when the tutorial refers to the data object with a URL that looks like a path.
Activity
MickeySegal commentedon Sep 18, 2017
Does anyone actually do anything after such reports? There are other issues with other Angular.io pages, but if it is a waste of time I won't bother to document the problems.
kapunahelewong commentedon Jan 4, 2018
Hi @MickeySegal, yes, we do. We process them and then figure out how each should be handled. Currently, we have a backlog we're working through right now, so it's taking a little time, but each issue does reach the appropriate team members. Right now, I'll apply the labels, then we'll figure out where the issue should go depending on those labels. Things that can effect that path are other related issues/PRs, level of effort, and what different roles (people) need to be consulted and who ultimately gets the assignment.
As you might imagine, issues that cover structural or tonal/thematic topics in the docs can involve discussion to find the best solutions and if they can be incorporated into existing work or if they need to be addressed on their own.
Tagging @jenniferfell, our docs team project manager, so she can see your suggestions.
@MickeySegal Thanks for your patience as we get through these and by all means, feel free to submit issues or PRs for anything you'd like to see improved.
sdepouw commentedon Jan 27, 2018
@MickeySegal Google led me straight here. I was scouring the tutorial to see if they ever explained the magic behind
api/heroes! I changed it to see if that path actually mattered. And it did of course, but I had no idea why. So thanks for posting it.sreevani-ship-it commentedon Oct 8, 2018
Fixed in PR #24445
angular-automatic-lock-bot commentedon Sep 14, 2019
This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.
Read more about our automatic conversation locking policy.
This action has been performed automatically by a bot.