Task #2470
closedIdea #2107: Recurring: ensure docs/tutorials are up-to-date with latest release.
Update docs for 2014-04-16 sprint
Updated by Brett Smith almost 11 years ago
- Remaining (hours) changed from 8.0 to 3.0
Yesterday I made progress through the bulk of the tutorial. I got caught on one snag where I was following the latest documentation, but matching code hadn't been deployed yet. Tom was working on that last night, so I should be able to keep going from here.
Updated by Brett Smith almost 11 years ago
- Status changed from New to In Progress
Updated by Brett Smith almost 11 years ago
- Status changed from In Progress to Resolved
- Remaining (hours) changed from 3.0 to 0.0
Pushed this branch upstream. 2490 is the review task.
Updated by Tom Clegg almost 11 years ago
Lots of good wording and detail fixes. (Thanks! I like it when I'm not the only detail-nitpicker...)
doc/user/topics/tutorial-job1.html.textile.liquid- "... Crunch would immediately return the output from someone else's past tutorial run."
- Hopefully this happened to you only because you have an administrator account, or some other user shared their job with you/everyone (which currently requires real dedication, but we'll have a Share UI soon).
- We should say "could" instead of "would" and say something about "if they marked it as public". (It should be clear that everything is private by default.)
- Another equally likely reason to include that no_reuse flag is that you might want to re-run it yourself while playing with the tutorials.
- "use the HEAD of the specified branch" -- I think we should be saying "tip", not "HEAD"...?
- "{output} is connected to the {input}" seems to me less clear than "{output} should be used as the {input}".
- (And I still think the sentence "This is a dependency." just sounds like it's trying to get a bigger "teaching moment" than it deserves...)
Every other change looks like an improvement.
Things that (maybe) should improve more while we're here:- Typo in "exclude_script_versions" example JSON, first comma should be a colon:
"exclude_script_versions", ["blacklisted_version_tag"],
- "Contents of the locator {foo}" seems a bit wrong. Is "contents of the collection located at {foo}" (or "whose locator is {foo}") too awkwardly verbose? Even "...the collection {foo}" would be grammatically sensible, I think.
- We should link to the real PuTTY home page, not the putty.org advertising/redirect site! http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
- ...or even a direct download link to the installer, http://the.earth.li/~sgtatham/putty/latest/x86/putty-0.63-installer.exe
Other minor nitpicks/suggestions (and mostly out of scope of "updating for this sprint")
[edit: moved these things to #2505]
Updated by Brett Smith almost 11 years ago
I've made a new push to implement your changes except the last section of out-of-scope stuff. I agree that a round of proper copyediting for stuff like that would be nice.
Updated by Tom Clegg almost 11 years ago
Looks great, I say merge. (I moved the unrelated todo's to #2505.)