Some feedback I got from someone offline: > Some feedback: also commit messages and code reviews are considered as > documentation, see https://hamatti.org/talks/contemporary-documentation/
I haven't yet watched the talk. I agree commit messages should be written well, though I don't know if that needs to be part of this guide (we have some things about that in the developer workflow). I don't know if I agree that code reviews are documentation. Conversations often contain information that was relevant at the time of the discussion, but aren't important for the end result. Sometimes they even mention things that are no longer correct at all. And unlike a documentation page, discussions around something like a code review should be left intact for archival purposes. but documentation should be something that is always edited and corrected when it becomes out of date. Even so, it may be worth mentioning these things (or not, I'll let you decide). Aaron Meurer On Thu, Oct 3, 2019 at 12:27 PM Lauren Glattly <[email protected]> wrote: > > Hi Sympyers, > > The new SymPy Documentation Style Guide that I'm putting together as part of > my Google Season of Docs project with SymPy is now available on the SymPy > Wiki: https://github.com/sympy/sympy/wiki/SymPy-Documentation-Style-Guide > > You'll notice that some of the new guidelines in the guide are qualified with > a Work in Progress note and an issue number. These are guidelines that are > dependent on resolving certain issues in order for the guide to be > implemented. If you are interested in working on any of these issues, the > full listing of Google Season of Docs related issues can be found here: > https://github.com/sympy/sympy/milestone/54 > > We would love to have some feedback from the SymPy community on the first > draft of this new style guide. In particular, we would like to know your > thoughts on these two issues: > > 1. What do you think of the new order for docstring sections? Do you think it > is more helpful for examples to occur earlier in the docstring to learn by > example, or do you prefer to have all of the information about a function, > such as parameters, before seeing the examples? > > 2. How do you think docstrings for classes that are mathematical functions > differ from other docstrings? Are there any other details you would like to > see included in this section? > > Please feel free to share any other feedback you may have about the new > guide. Please share any feedback you have by October 21st to allow for ample > time for concerns to be addressed. After October 21st I will be finalizing > the guide and starting the process to merge it with SymPy's documentation. > > Thank you in advance for your thoughts and comments! > Lauren -- You received this message because you are subscribed to the Google Groups "sympy" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CAKgW%3D6JgPzttpcMGDFtWdnLcpc37bn-8Za%3DFW%3DAyMY-mL7E2Vg%40mail.gmail.com.
