[pypy-issue] [issue1407] Getting Started docs: misleading elements and suggested improvments

[Roy Feldman]

New submission from Roy Feldman <roy.feldman at gmail.com>:

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 <tracker at bugs.pypy.org>
<https://bugs.pypy.org/issue1407>
________________________________________