4 ms·

When I document, or write commit messages, I don't really _care_ if other folks will ever look at them. Documentation is a gift for future me. If something wasn

When I document, or write commit messages, I don't really _care_ if other folks will ever look at them. Documentation is a gift for future me. If something wasn't obvious to figure out, or a potential source of future problems, I want it written down, so if _I_ go looking for info, it's there. The fact that things are now documented for other folks is just a side benefit.

ChrisMarshallNY 3y ago
This. I write documentation for me. Very few folks ever use my published code, which is fine by me. I publish it, because treating my packages as atomic, ship-ready, high-Quality products, forces me to take great care, in each and every one. Which means, when I use them in my other work, I don't have to worry about them. My take on documentation is thus: https://littlegreenviper.com/miscellany/leaving-a-legacy/ https://littlegreenviper.com/miscellany/leaving-a-legacy/
- mixmastamyk 3y ago
  Documentation is for everyone. Put it where everyone can read it, not hidden in the most esoteric place possible, via a very unfriendly tool. I do that often and call it the developer guide. After the user and ops guides. Not to mention comment and doc strings about why in the current code.
  - _Algernon_ 3y ago
    This entire thread is making me feel like I'm taking a crazy pill. A simple git log is considered "esoteric" these days? No extra command line arguments are required to read the entire commit message. If so software "engineering" is truly a dead discipline. I guess the "move fast and break things" crowd have taken over.
    - ChrisMarshallNY 3y ago
      Not sure why you're attacking me. I don't remember saying anything offensive. Anyway, I've never been a fan of "moving fast and breaking." Might want to give that blog entry I linked, a read.
    - mixmastamyk 3y ago
      Never worked with other people? Git as a thing is off the table. Which commit? One month ago or three? Pro{gram,ject,duct}M, SME, QA, or user wants to know why? Do they even have a login to the systems they’d need? Is there search so they could find it themselves when you quit? Or you could send them a link to the docs.

ChrisMarshallNY 3y ago

This. I write documentation for me. Very few folks ever use my published code, which is fine by me. I publish it, because treating my packages as atomic, ship-ready, high-Quality products, forces me to take great care, in each and every one. Which means, when I use them in my other work, I don't have to worry about them. My take on documentation is thus: https://littlegreenviper.com/miscellany/leaving-a-legacy/ https://littlegreenviper.com/miscellany/leaving-a-legacy/

mixmastamyk 3y ago
Documentation is for everyone. Put it where everyone can read it, not hidden in the most esoteric place possible, via a very unfriendly tool. I do that often and call it the developer guide. After the user and ops guides. Not to mention comment and doc strings about why in the current code.
- _Algernon_ 3y ago
  This entire thread is making me feel like I'm taking a crazy pill. A simple git log is considered "esoteric" these days? No extra command line arguments are required to read the entire commit message. If so software "engineering" is truly a dead discipline. I guess the "move fast and break things" crowd have taken over.
  - ChrisMarshallNY 3y ago
    Not sure why you're attacking me. I don't remember saying anything offensive. Anyway, I've never been a fan of "moving fast and breaking." Might want to give that blog entry I linked, a read.
  - mixmastamyk 3y ago
    Never worked with other people? Git as a thing is off the table. Which commit? One month ago or three? Pro{gram,ject,duct}M, SME, QA, or user wants to know why? Do they even have a login to the systems they’d need? Is there search so they could find it themselves when you quit? Or you could send them a link to the docs.