From OpenStreetMap Wiki
Jump to navigation Jump to search

I'm a mapper near Baltimore, Maryland, USA. I have drawn maps since I was a kid. Coming to think of it, I probably spent too much time drawing them, and not enough on homework. And I'm probably spending too much time on here now. Cest la vie...

I think the main reason that software development is oftentimes such a complete and utter WTF is that the people who write code can't document it to save their lives. My pet peeves in documentation are:

  • Excessive use of jargon.
  • Information scattered here, there, and everywhere. ("For the answer to your question, see comment number 17 to my blog post of November 13, 2003, and the followup to it in comment number 43 in his blog post of February 31, 2005, followed by the twenty-second email message on the developers' listserv for June 4, 2006. Which you have to get from the archive and unzip first. Unless the moon is full, in which case...")
  • Documentation that explains what rather than why or how. (My favorite: "Checking the check box turns [the option] on, and clearing the check box turns [the option] off." No! You're positively shitting me! How about telling me, gee, I don't know, how the option affects the program, why you included this option, etc.)

These things promote high barriers to entry, which is, perhaps, the way a lot of developers want it, unfortunately. So I'm looking to change that with my editing of the wiki.