More detail about render failure.

The note about readme-renderer has been moved to the new FAQ item
with a pointer from its previous location.

Author: sgillies

warehouse/templates/pages/help.html

@@ -569,7 +569,7 @@ <h3 id="request-ownership">{{ request_ownership() }}</h3>
         <h3 id="description-content-type">{{ description_content_type() }}</h3>
         <p>{% trans href='http://docutils.sourceforge.net/rst.html', title=gettext('External link') %}By default, an upload's description will render with <a href="{{ href }}" title="{{ title }}" target="_blank" rel="noopener">reStructuredText</a>. If the description is in an alternate format like Markdown, a package may set the <code>long_description_content_type</code> in <code>setup.py</code> to the alternate format.{% endtrans %}</p>
         <p>{% trans href='https://packaging.python.org/tutorials/distributing-packages/#description', title=gettext('External link') %}Refer to the <a href="{{ href }}" title="{{ title }}" target="_blank" rel="noopener">Python Packaging User Guide</a> for details on the available formats.{% endtrans %}</p>
-        <p>{% trans href='https://pypi.org/project/readme_renderer/' %}PyPI will reject uploads if the description fails to render. To check a description locally for validity, you may use <a href="{{ href }}">readme_renderer</a>, which is the same description renderer used by PyPI.{% endtrans %}</p>
+        <p>For how to check a description for validity, see also: <a href="#description-render-failure">{{ description_render_failure() }}</a></p>
 
         <h3 id="file-size-limit">{{ file_size_limit() }}</h3>
         <p>
@@ -626,6 +626,13 @@ <h3 id="vulnerability-data">{{ vulnerability_data() }}</h3>
       <section class="faq-group" id="troubleshooting">
         <h2>{% trans %}Troubleshooting{% endtrans %}</h2>
 
+        <h3 id="description-render-failure">{{ description_render_failure() }}</h3>
+        <p>
+          {% trans trimmed readme_renderer_href='https://pypi.org/project/readme_renderer/', twine_check_href='https://twine.readthedocs.io/en/latest/#twine-check', title=gettext('External link') %}
+            PyPI will reject uploads if the package description fails to render. You may <a href="{{ twine_check_href }}" title="{{ title }}">use twine's check command</a> or <a href="{{ readme_renderer_href }}">readme_renderer</a>, the same description renderer used by PyPI, to locally check a description for validity.
+          {% endtrans %}
+        </p>
+
         <h3 id="login-problem">{{ login_problem() }}</h3>
         <p>{% trans %}If you've forgotten your PyPI password but you remember your email address or username, follow these steps to reset your password:{% endtrans %}</p>
         <ol>
@@ -865,13 +872,6 @@ <h3 id="pronunciation">{{ pronunciation() }}</h3>
           {% endtrans %}
         </p>
 
-        <h3 id="description-render-failure">{{ description_render_failure() }}</h3>
-        <p>
-          {% trans trimmed href='https://twine.readthedocs.io/en/latest/#twine-check', title=gettext('External link') %}
-            To diagnose a description render error, use twine's <a href="{{ href }}" title="{{ title }}">check command</a>.
-          {% endtrans %}
-        </p>
-
       </section>
     </div>
   </div>