Where is PEP 8 for Technical Documentation?

March 18, 2010  /  Home

Anyone who has programmed in Python for a considerable length of time will at least have some passing familiarity with PEP 8 — the document that goes into an incredible level of detail in dictating precisely how code should be written. While its primary goal is to ensure that Python code is written in a consistent fashion throughout the community, therefore making it as easy as possible to read, it also provides one of many aspects that makes programming in Python an incredibly efficient process — it negates the need for a lot of decision making around any of the choices one might come across that are already covered in PEP 8.

I’ve recently been spending a lot of time writing technical documentation. While it’s been interesting doing something different for a change, the perfectionist in me is constantly frustrated with finding myself using inconsistent language across different sections when faced with the exact same context, for example:

Are these types of ambiguities in technical writing something that professional editors typically deal with? What I’d love to see is something like PEP 8 for technical documentation.