Write about what you read

Today, just minutes ago, I stumbled across Andy's working notes. What the hell kind of organizing system is this? It's like a wiki, but only notes, with a million links, and tiny pages. I don't know what it is, or if it would work for me, but I LIKE IT.

Anyway, within 10 minutes of finding this delightful little place, I found myself in a whole new Wiki rabbit hole, or if you prefer, XKCD: The problem with Wikipedia.

The number of tabs in chrome is directly proportional to how happy I am. I am very very happy. Chrome is very very sad.

Now that we've covered all that, back to

Write about what you read

Go read his note. Yes, that's the same link as above. It's important dammit. And way, way better than whatever I was gonna write about it. Hell, the only reason I'm writing about it is that his note (yeah I said it's important) told me to.

So, now that you've read his version (deal with it) feel free to ignore mine.

Write about what you read - Not just Andy's link this time

Andy's write about what you read (sorry, not sorry) connected with something deep inside me, near the spleen, where I keep important thoughts. I've long been a proponent of writing things down. Documentation matters. Don't screw the next guy. Leave things better than you get them.

Make tiny notes as you work. Put them somewhere only you can see. Only keep one note file. Keep your note file short. Use this to write something for the next guy.

• Make tiny notes as you work
• Things you don't want to forget
• TODO items
• New project ideas
• What tools and setup are required, as you find them
• Missing steps in existing documents
• Write these somewhere only you see
• Don't waste time making them clear for somebody else to understand, this is only for you at this point
• Only keep one note file
• I generally keep some notes in my Tasks.txt file that is eternally open
• If you spread them around to multiple files, you will NEVER get around to the next steps
• Keep your note file short
• Short is relative
• If you have trouble finding what you are looking for in your note file, it's too damn long
• What do you do if it feels too long? Follow the next step
• Use this to write something for the next guy
• The next guy might be you in a couple years
• The next guy might be the poor bastard that takes over your projects when you move on to bigger and better things
• The next guy might get to pick things up after your slow ass gets mowed down by a bus, because you were too damned busy arguing with trolls on FaceRedAgram+©™ to see where you were going. Jerk.
• Use this to write something for the next guy
• Find where each of your little notes could fit into the existing documentation
• Don't have existing documentation? Time to start
• As your notes are incorporated into the documentation, remove them from your private notes

Maybe someday I'll write something about professionalism. I'll try to swear less in that one. Today though, just a footnote about our profession: Software development is treated far to much like an 'art' instead of a 'science'. An item of 'art' is one off, unique. To be 'science', it needs to be reproducible. Given your documentation, source code and other artifacts, any other skilled software developer should be able to reproduce the working software.

References and other good stuff:

• Andy's write about what you read: https://notes.andymatuschak.org/zg3fYweZpbHeBTpcYke5mF4ZfrJutYcQEtFo (last time I swear)
• ESR's Documentation as knowledge capture: http://esr.ibiblio.org/?p=8741