pytorch / pytorch/tutorials

Distributed Data Parallel Tutorial UX improvement suggestion

Open
#1,637 10 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

content docathon-h2-2023 medium
Dominant language
Python
Stars
9.3k
Forks
4.4k
Avg merge
1d 21h
Merged PRs (30d)
4

Description

referring to the tutorial: https://pytorch.org/tutorials/intermediate/ddp_tutorial.html

Though the tutorial is broken down into sections, it doesn't show how to actually run the code from each section until the very end of the tutorial.

The code as presented in each section only gives function definitions despite the tutorial text carrying on as though the user is supposed to be able to see something from running the code snippet that has been provided. This combination of info presented in a way that seems self contained, with code that seems self contained but isn't was rather confusing.

to remedy this issue I think it'd make things easier if either
A) the code to run each section is included in that code snippet
B) a notebook is included in the tutorial so users can see how the code is actually run, without having to guess/find that this code is only listed at the bottom of the tutorial
C) mention that a reasonable default set to run the code snippets can be found at the bottom of the tutorial.

additional data point: Before I noticed the code at the bottom of the tutorial to invoke the functions, I looked for other resources and came across an external tutorial: https://yangkky.github.io/2019/07/08/distributed-pytorch-tutorial.html which specifically references the pytorch DDP tutorial and raises similar criticism. Though some of the flaws pointed out have been fixed, this piece remains

cc @sekyondaMeta @svekars @carljparker @NicolasHug @kit1980 @subramen

Contributor guide

Open the contributing guide

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 with the Distributed Data Parallel tutorial at https://pytorch.org/tutorials/intermediate/ddp_tutorial.html, comparing each section's code with the invocation code at the bottom. The documentation is done when readers can understand how to run each section, either through runnable section examples, a notebook, or clear guidance pointing to the invocation code.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, pytorch
Domain
distributed-systems, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.