New submission from Roy Feldman <[email protected]>: Currently, the bulk of the Getting Started page is misleading with respect to the "Where to go from here" section near the bottom. http://doc.pypy.org/en/latest/getting-started.html
Getting Started both describes how to download and install a pre-built PyPy and how to clone the repository. These appear as equal alternatives with the caveat in the "Clone the Repository" section: "If you prefer to compile PyPy by yourself, or if you want to modify it, you will need to obtain a copy of the sources." Not that most readers who read Getting Started are not planning to immediately start modifying the source code. The "Clone the Repository" section is immediately followed by "Where to go from here." The first two activities in that section require cloning the repository, but that is not clear to the reader. Namely, "Building and using the PyPy's Python interpreter" and "Learning more about the Rpython toolchain and how to develop (with) PyPy. Adding to the readers confusion is the beginning of the description for the first activity. On the page titled "Getting Started with PyPy’s Python Interpreter", the third sentence states "To actually use PyPy’s Python interpreter, the first thing to do is to download a pre-built PyPy for your architecture." This is very misleading in this context and should be replaced with instructions to clone the repository. http://doc.pypy.org/en/latest/getting-started-python.html Note that the third activity, "Tutorial for how to write an interpreter with the RPython toolchain and make it fast", clearly states that cloning the repository is required. http://morepypy.blogspot.com/2011/04/tutorial-writing-interpreter-with-pypy.html One more suggestion. Unless there good stylistic reasons to the contrary, the text of links in the docs should match the titles of the pages they link. For example, on the Getting Started page: - Building and using PyPy’s Python interpreter -> Getting Started with the PyPy's Interpreter - Learning more about the RPython toolchain and how to develop (with) PyPy -> Getting Started with the Translation Toolchain and Development Process These may seem like little things, but consistency helps avoid reader confusion and makes the documentation look more professional. ---------- messages: 5375 nosy: pypy-issue priority: bug status: unread title: Getting Started docs: misleading elements and suggested improvments ________________________________________ PyPy bug tracker <[email protected]> <https://bugs.pypy.org/issue1407> ________________________________________ _______________________________________________ pypy-issue mailing list [email protected] http://mail.python.org/mailman/listinfo/pypy-issue
