From 19bc8bbe37044b9f23d80bb282758071d0d8bf15 Mon Sep 17 00:00:00 2001 From: bjnath Date: Thu, 11 Jun 2020 13:37:32 -0400 Subject: DOC: Tighten howto-docs guide #16259 (#16385) * DOC: rreword much of the howto-docs guide --- doc/source/dev/howto-docs.rst | 265 ++++++++++++++++++++++-------------------- 1 file changed, 136 insertions(+), 129 deletions(-) (limited to 'doc/source/dev') diff --git a/doc/source/dev/howto-docs.rst b/doc/source/dev/howto-docs.rst index e8bafd254..17194bd58 100644 --- a/doc/source/dev/howto-docs.rst +++ b/doc/source/dev/howto-docs.rst @@ -4,146 +4,153 @@ How to contribute to the NumPy documentation ############################################ -The *Documentation* for a software project is the set of reference, -instructional, educational, informative material generated by the project -developers and contributors, as well as discussions, presentations, videos and -other user-generated content. It may include learning-oriented content (such as -tutorials and how-tos), use-cases or in-depth explanations and reference for -developers. - -If you're reading this page, you probably want to help. This guide is meant to -help you decide which kind of content you'll write, as well as give you some -tips and instructions for submitting it to the official NumPy documentation -(that is, the documentation that ships with NumPy and lives on the -:ref:`official project pages `). Keep in mind that if you -don't want to do this, writing a tutorial on your own blog, creating a YouTube -video or answering questions on social media or Stack Overflow are also great -contributions! - -NumPy has a Documentation Team. We have open meetings on Zoom every three weeks -and invite everyone to join. Don't hesitate to reach out if you have questions -or just need someone to guide you through your first steps - we're always happy -to help. Meetings are usually announced on the `numpy-discussion mailing list -`__. Meeting minutes -are taken `on hackmd.io `__ and stored -in the `NumPy Archive repository `__. - -You can find larger planned and in-progress documentation improvement ideas `at +This guide will help you decide what to contribute and how to submit it to the +official NumPy documentation. + +****************************************************************************** +Documentation team meetings +****************************************************************************** + +The NumPy community has set a firm goal of improving its documentation. We +hold regular documentation meetings on Zoom (dates are announced on the +`numpy-discussion mailing list +`__), and everyone +is welcome. Reach out if you have questions or need +someone to guide you through your first steps -- we're happy to help. +Minutes are taken `on hackmd.io `__ +and stored in the `NumPy Archive repository +`__. + +************************* +What's needed +************************* +NumPy docs have the details covered. API reference +documentation is generated directly from +`docstrings `_ in the code +when the documentation is :ref:`built`. + +What we lack are docs with broader scope -- tutorials, how-tos, and explanations. +Reporting defects is another way to contribute. We discuss both. + +************************* +Contributing fixes +************************* + +We're eager to hear about and fix doc defects. But to attack the biggest +problems we end up having to defer or overlook some bug reports. Here are the +best defects to go after. + +Top priority goes to **technical inaccuracies** -- a docstring missing a +parameter, a faulty description of a function/parameter/method, and so on. +Other "structural" defects like broken links also get priority. All these fixes +are easy to confirm and put in place. You can submit +a `pull request (PR) `__ +with the fix, if you know how to do that; otherwise please `open an issue +`__. + +**Typos and misspellings** fall on a lower rung; we welcome hearing about them but +may not be able to fix them promptly. These too can be handled as pull +requests or issues. + +Obvious **wording** mistakes (like leaving out a "not") fall into the typo +category, but other rewordings -- even for grammar -- require a judgment call, +which raises the bar. Test the waters by first presenting the fix as an issue. + +****************************************************************************** +Contributing new pages +****************************************************************************** + +Your frustrations using our documents are our best guide to what needs fixing. + +If you write a missing doc you join the front line of open source, but it's +a meaningful contribution just to let us know what's missing. If you want to +compose a doc, run your thoughts by the `mailing list +`__ for futher +ideas and feedback. If you want to alert us to a gap, +`open an issue `__. See +`this issue `__ for an example. + +If you're looking for subjects, our formal roadmap for documentation is a +*NumPy Enhancement Proposal (NEP)*, +`NEP 44 - Restructuring the NumPy Documentation `__. +It identifies areas where our docs need help and lists several +additions we'd like to see, including Jupyter notebooks. + +You can find larger planned and in-progress ideas `at our GitHub project `__. -Current vision for the documentation: NEP 44 --------------------------------------------- +.. _tutorials_howtos_explanations: -Recently, the NumPy community approved a *NumPy Enhancement Proposal (NEP)* -about documentation, -:ref:`NEP 44 - Restructuring the NumPy Documentation `. -**Where is the documentation?** +Formula writing +============================================================================== +There are formulas for writing useful documents, and four formulas +cover nearly everything. There are four formulas because there are four +categories of document -- ``tutorial``, ``how-to guide``, ``explanation``, +and ``reference``. The insight that docs divide up this way belongs to +Daniele Procida, who goes on +`in this short article `__ to explain +the differences and reveal the formulas. When you begin a document or +propose one, have in mind which of these types it will be. -The main page for the :ref:`NumPy Documentation ` lists -several categories. The documents mentioned there live in different places. -- **Tutorials, How-Tos, Explanations:** These documents are stored in the NumPy - source code tree, which means that in order to add them to the official - documentation, you have to download the NumPy source code, - :ref:`build it ` and submit your changes via a - :ref:`GitHub pull request `. +.. _contributing: -- **API Reference:** These are mainly the result of rendering the NumPy code - `docstrings `__ into formatted - documents. They are automatically generated when the NumPy documentation is - :ref:`built from source`. -**Datasets** +More on contributing +============================================================================== -If you are writing a tutorial or how-to, we encourage you to use real images and -data (provided they are appropriately licensed and available). This makes the -material more engaging for readers, and choosing the right data can add -pedagogical value to your content. +Don't worry if English is not your first language, or if you can only come up +with a rough draft. Open source is a community effort. Do your best -- we'll +help fix issues. -*Note: currently we cannot easily use data in other packages (except, e.g., from -SciPy or Matplotlib). We plan to create a dedicated datasets package, but that's -not ready yet - please discuss with us if you have data sources in mind.* +Images and real-life data make text more engaging and powerful, but be sure +what you use is appropriately licensed and available. Here again, even a rough +idea for artwork can be polished by others. -Creating new content --------------------- +For now, the only data formats accepted by NumPy are those also used by other +Python scientific libraries like pandas, SciPy, or Matplotlib. We're +developing a package to accept more formats; contact us for details. -The documentation is written in restructuredText, which is the format required -by Sphinx, the tool most Python projects use to automatically build and link the -documentation within the project. You can read the -`Quick reStructuredText Guide +NumPy documentation is kept in the source code tree. To get your document +into the docbase you must download the tree, :ref:`build it +`, and submit a pull request. If GitHub and pull requests +are new to you, check our :ref:`Contributor Guide `. + +Our markup language is reStructuredText (rST), which is more elaborate than +Markdown. Sphinx, the tool many Python projects use to build and link project +documentation, converts the rST into HTML and other formats. For more on +rST, see the `Quick reStructuredText Guide `__ or the `reStructuredText Primer -`__ for -more information. - -If you have already decided which type of document you want to write, you can -check out the following specific guides: - -- Guide to writing Tutorials (TODO) -- :ref:`Guide to writing reference (API) documentation: the numpydoc docstring - guide ` - -Major additions to the documentation (e.g. new tutorials) should be proposed to -the `mailing list -`__. - -Other ways to contribute ------------------------- - -Correcting technical inaccuracies in the documentation are high priority. For -example, if a docstring is missing a parameter or the description of a -fuction/parameter/method etc. is incorrect. Other "structural" defects like -broken links are also high priority. - -Proposals for changes that improve the clarity of the documentation are welcome. -However, "clarity" is a bit subjective, so such proposals are best made by -raising issues that describe what could be improved in the current -documentation. Proposals that include specific suggestions for the improvement -are encouraged as the proposed changes helps frame the discussion. - -Based on the above characterization, "high-priority" changes (i.e. fixing -technical inaccuracies, broken links, etc.) can be proposed via pull requests -directly as they are straightforward to review. Other changes should be raised -as issues first so that the discussion can happen before you make major -modifications, which in principle saves you from wasting your time on -undesired changes. - -If you see a good tutorial, how-to or explanation that is not included in the -official documentation, you can suggest it to be added by `opening an issue on -GitHub `__. Similarly, opening issues to -suggest a tutorial, how-to or explanation that you can't find anywhere is a -great way to help the documentation team direct efforts towards what users are -looking for. `See this issue `__ -for an example of how to do this. - -Finally, if you detect a typo or an error in the documentation, or would like to -suggest a different approach, you can also open an issue or submit a pull -request with your suggestion. Keep in mind that changes fixing -grammatical/spelling errors are welcome but not necessarily the highest -priority. "Grammatical correctness" often gets confused with "style" which can -result in unfruitful discussions that don't necessarily improve anything. -Changes that modify wording or rearrange phrasing without changing the technical -content are discouraged. If you think that a different wording improves clarity, -you should open an issue as noted above, but again, changes along these lines -very often tend to be highly subjective and not necessarily do much to improve -the quality of the documentation. - -**Final tips** - -- Don't worry if English is not your first language. Do your best - we'll revise - your content and make sure we fix any issues with the code or text. -- If you are unsure whether your tutorial is useful to the community, consider - submitting an issue on GitHub suggesting it, or asking on the mailing - list or Stack Overflow. -- If you are unfamiliar with git/GitHub or the process of submitting a pull - request (PR), check our :ref:`Contributor Guide `. - -**Other interesting material** - -- `writethedocs.org `__ has a lot of interesting - resources for technical writing. -- Google offers two free `Technical Writing Courses - `__ -- `Software Carpentry `__ has a lot of - nice recommendations for creating educational material. +`__ + + +************************************************************ +Contributing indirectly +************************************************************ + +If you run across outside material that would be a useful addition to the +NumPy docs, let us know by `opening an issue `__. + +You don't have to contribute here to contribute to NumPy. You've contributed +if you write a tutorial on your blog, create a YouTube video, or answer questions +on Stack Overflow and other sites. + + +************************************************************ +Documentation reading +************************************************************ + +- The leading organization of technical writers, + `Write the Docs `__, + holds conferences, hosts learning resources, and runs a Slack channel. + +- "Every engineer is also a writer," says Google's + `collection of technical writing resources `__, + which includes free online courses for developers in planning and writing + documents. + +- `Software Carpentry's `__ mission is + teaching software to researchers. In addition to hosting the curriculum, the + website explains how to present ideas effectively. -- cgit v1.2.1