Matt Bogosian <eb3f73+python+...@yaymail.com> added the comment:
Please consider highlighting that dicts are not included in the documentation. While *technically* true, this ... > compact impacts the way that long sequences (lists, tuples, sets, etc) are > formatted. If compact is false (the default) then each item of a sequence > will be formatted on a separate line. If compact is true, as many items as > will fit within the width will be formatted on each output line. ... has several problems. First, sequence is a term of art that also has a common meaning. This creates a potential ambiguity in the understanding of the reader. Resolving that ambiguity in this context requires that readers have already internalized that dicts are not Python sequences. Those new to Python may not understand the (to them, subtle) differences between Python's iterables and sequences. Second, the "etc" only expands that ambiguity and invites confusion. Third, the term "items" is strongly associated with dicts and is used several times throughout the paragraph. This ... > According to https://docs.python.org/3/library/pprint.html compact impacts > the way that sequences are displayed, and a dict is not a sequence. ... is unhelpfully pedantic, and ignorant of the needs of the newcomer (a key demographic of documentation). Documentation is a core product surface with a diverse audience. Rather than focus on technical correctness, documentation authors should focus on accessibility. Redundancy is a feature, not a bug. You can't predict how your reader got to that slice of the documentation. Imagine this as an opportunity to educate or reinforce concepts for readers, not as an opportunity to argue from a position of technical superiority. The fact that there are now four developers who have taken their time to file patches, bugs, and comments is pretty strong signal that confusion exists among the audience and that the documentation is insufficient. ---------- nosy: +posita _______________________________________ Python tracker <rep...@bugs.python.org> <https://bugs.python.org/issue34798> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
