Use of "Payload" is ambiguous as it's defined in spec as a base32-encoded data stream containing the version byte, hash, and checksum. It should be more clear that the data being calculated is the version byte, hash, and zeroes for the checksum rather than simply saying item 3 is payload and item 4 is zeroes for the checksum. It's likely new developers will not include the version byte given the wording of the current spec, assuming "payload" to mean "key hash".
It would also be useful to clarify that while every number is limited to 5 bits, they still each use up all 8 bits (with the exception of the chunked payload), with three empty spacer bits per byte. The "5 zero bits" and "Eight zeroes" wording is extremely confusing. Either describe it as an array of bytes with the prefix cut down to the lower 5 bits of each letter and the payload reorganized in 5-bit chunks, or describe it as an array of 5-bit values stored in isomorphic bytes. Using 5-bits and bytes together is just mean to the reader.
Finally, the fact that the hash should be base32-encoded separately from the payload would seem to be of vital importance, both for encoding and decoding. This seems to be glossed over. It should also be mentioned for verification purposes that the last 8 base-32 encoded characters are the hash, which should be removed from the address before splitting into prefix and payload. All the pieces of the definition are there, in a way, but they're not set out as clearly as they should be.
The first and last problem can both be solved by improving the definition of Payload to mean the Version Byte and Key Hash, and defining the Checksum as a suffix to the address entire, rather than trying to say that the Checksum is part of the Payload and that it's all one stream of base-32 encoded data. It's not one stream, it's two.
Use of "Payload" is ambiguous as it's defined in spec as a base32-encoded data stream containing the version byte, hash, and checksum. It should be more clear that the data being calculated is the version byte, hash, and zeroes for the checksum rather than simply saying item 3 is payload and item 4 is zeroes for the checksum. It's likely new developers will not include the version byte given the wording of the current spec, assuming "payload" to mean "key hash". It would also be useful to clarify that while every number is limited to 5 bits, they still each use up all 8 bits (with the exception of the chunked payload), with three empty spacer bits per byte. The "5 zero bits" and "Eight zeroes" wording is extremely confusing. Either describe it as an array of bytes with the prefix cut down to the lower 5 bits of each letter and the payload reorganized in 5-bit chunks, or describe it as an array of 5-bit values stored in isomorphic bytes. Using 5-bits and bytes together is just mean to the reader. Finally, the fact that the hash should be base32-encoded separately from the payload would seem to be of vital importance, both for encoding and decoding. This seems to be glossed over. It should also be mentioned for verification purposes that the last 8 base-32 encoded characters are the hash, which should be removed from the address before splitting into prefix and payload. All the pieces of the definition are there, in a way, but they're not set out as clearly as they should be.
The first and last problem can both be solved by improving the definition of Payload to mean the Version Byte and Key Hash, and defining the Checksum as a suffix to the address entire, rather than trying to say that the Checksum is part of the Payload and that it's all one stream of base-32 encoded data. It's not one stream, it's two.