Why Projects Should Have "What's New" Documents

Describes the speaker’s experience writing What’s New documents covering the new features in each Python 2.x release. The editorial policies will be summarized, and the speaker argues that large projects should include a “What’s New” as part of their standard documentation set.

Transcript

1. Why Projects Should Have "What's New" Documents Andrew Kuchling, Cox Digital Media WriteTheDocs 2013 amk@amk.ca - from 1999 to 2010 - I wrote What’s New docs for each version of Python from 2.0 to 2.7 - 2.0 was co-written with Moshe Zadka. - these described the new features in each version - largely the only way I contributed to Python core development for that decade. - will argue that projects should include What's New articles in their documentation plans - to support this, will explain their usefulness & discuss the editorial policies.
2. README * Type/Class Unification: A new way of introspecting instances of built-in types and the ability to subclass built-in types have been added. * Iterators and generators were added. - Most projects have a README file - Python 2.2's README contains entries like this: - type/class unification? this desc. doesn't explain the usefulness/significance. - iterators/generators: two language features described in a single line - can I have more detail, please?
3. Misc/NEWS - New-style classes can now have a __del__ method, which is called when the instance is deleted (just like for classic classes). - C.__doc__ now works as expected for new-style classes (in 2.2a4 it always returned None, even when there was a class docstring). - Has a second file: Misc/NEWS - many projects call this the changelog. - very detailed - type/class unification had an item-by-item section of its own in NEWS - featuring every increment of functionality as it was added.
4. Misc/NEWS - Issue #9075: In the ssl module, remove the setting of a 'debug' flag on an OpenSSL structure. - Issue #6589: clean up asyncore.socket_map in case smtpd.SMTPServer constructor raises an exception. - there are also entries for every change and bug-fix - will this affect my code? is it important?
5. http://docs.python.org/2.7/whatsnew/ - goal for What's New was: - highlight significant changes - provide a tutorial introduction to new features - the benefit to users is clear - unexpectedly, there were benefits for the Python developers as well
6. User Benefits Fills gap between announcements and NEWS, specs. Useful for experienced users who upgrade Tutorial style puts new features in perspective Users liked them because: - as I envisioned, they were at the right level - announcements/README have too little detail - Misc/NEWS has too much detail - Specs are time-consuming to read - convenient when your env. goes up one or two versions - tutorial style is useful for less experienced programmers - puts new features in perspective - can explain the purpose of a feature & its design - give usage examples
7. Developer Benefits History: When was feature X introduced? Alternative implementations: - what do we need to keep up with? To my surprise, Python core developers also found them useful: - when was feature X introduced? - alt. interpreters: what does my impl. need to keep up with? my most unexpected benefit: - writing What's New adds a third level of review:
8. Levels of review: Review commits as they're made - most projects review commits - review can be done after the fact, by sending commit msgs to a mailing list - or, using tools such as Review Board to review commits before they're applied.
9. Levels of review: Review commits as they're made First: Write a Python Enhancement Proposal - Python being widely-used language w/ multiple implementations - it's important not to break existing code too much - or make life too hard for other impls. Python devs therefore introduced PEPs - documents describing a possible feature, its implementation, alt. approaches - they are discussed & reviewed, often before any code is written
10. Levels of review: Review commits as they're made After: Add to What's New First: Write a Python Enhancement Proposal - What's New adds a 3rd level of review, by me. - writing material meant reviewing all of: - the PEP - the documentation that had been written - often had to look at the current code, or indiv. commits - sometimes I found omissions: features in the PEP that: - weren't implemented - implemented, but not documented. - implemented differently Such issues could be raised on python-dev.
11. Process I'll describe the process & editorial policies. Suggest you consider & adapt them for your projects. - a skeleton document was added when each new dev. branch was created - over time I developed a consistent ordering of sections - changes to development process - PEPs (sorted numerically) - Other Language Changes, where small changes could be swept - Libraries - subscribed to python-checkins - saved commit messages to a folder - processed them periodically
12. Editorial Policies 1. Be useful to the reader. The overriding principle is to provide useful info to the reader. Imagined reader is an intermediate developer - but not necessarily a CS graduate - or someone who is aware of Python core development at all. Explain and motivate new features - Example: Py2.2's type/class unification: - described the benefits (being able to subclass C types; properties) - explained difference between old-style and new-style classes - ... and the underlying impl. tool of attribute descriptors. - how multiple inheritance differed - It was a short tutorial in its own right.
13. Editorial Policies 1. Be useful to the reader. Background or non-Python material was discussed. - Linked external sources. Example: Python 2.4 introduced a decimal data type. - I explained how floating point numbers introduce inaccuracies - 1/10 can be displayed as 0.1000000001. - wrote 1/2 a page of explanation - & linked to pages explaining FP inaccuracy in more detail, - & and to the General Decimal Spec. describing the arithmetic rules implemented
14. Editorial Policies 1. Be useful to the reader. Also incorporated references into Python's development process - we've already seen how PEPs were employed as sections - also linked issues in bug tracker - sometimes even posts on the python-dev mailing list
15. Editorial Policies 1. Be useful to the reader. Credited sources of inspiration (other languages, ext. libraries) - software is an engr. discipline; cherry-picking ideas is good & to be encouraged. Also recorded who contributed the patch - who wrote the PEP, who implemented it. - in this case, record authors of a competing patch Rationale: - Python has many contributors; people often submit a single bugfix or improvement.
16. Editorial Policies 2. Focus on changes of wide interest. Rationale: some changes are v. specialized. This is unrelated to how much work a change required. This is necessary to occupy the middle ground. The detailed changelog and the VCS logs are always there for completeness.
17. Editorial Policies 3. Write new explanations/examples Finally, I made things harder for myself - No cut-and-paste from existing PEPs or docs - Invent new examples instead Rationale: - WN provides an alternate explanation - if you don't understand the docs or PEP, a diff. approach might help - forces me to analyze the language feature more closely
18. Conclusion Writing What's New has some cost - consumed 1 spare-time dev before release of new version. Didn't require much maintenance afterwards. - typos and errors to fix. - Python minor releases don't include the sort of significant change that gets into what's new. Writing them: - is useful for users - provides a detailed review by a core developer. - review *before* the final project release is made. I suggest you consider making a "What's New" article part of the standard documentation for your projects.
19. Conclusion speakerdeck.com/akuchling/whats-new amk@amk.ca Questions?