• 0 Posts
  • 37 Comments
Joined 2 years ago
cake
Cake day: June 18th, 2023

help-circle





  • Important/generalized patterns reveal themselves over time. I generally push for people to just write the specific thing they need for the given context and then if the same pattern shows up elsewhere, promote the code to a shared library. It’s really hard to anticipate the correct abstraction right from the start, and it’s easy to include a bunch of “just in case” parameterization that bloats the interface and adds a lot of conceptual overhead.

    That being said, with low-leverage/complexity code like html views, repetition isn’t as problematic. Although, I do think that HTML components have matured enough to be the correct unit of abstraction, not CSS classes.


  • Demo videos are not “documentation.” They are “demos.”

    If you want someone to repeat your steps, it should be code or CLI commands. You can write more descriptive text, but as soon as you reference pictures to show something, you’re introducing ambiguity that text/code can avoid.

    UIs change faster than videos and screenshots, as you said, can’t be searched, and are generally less accessible than text.

    The source files for documentation should also live side-by-side with the code in the repo. As soon as it goes anywhere else, it immediately goes out of date.



  • I think this is an important lesson in general, and one that applies in other contexts:

    You don’t need a “cheatsheet” for most stuff. The things you do all the time will become muscle memory, and the other stuff is easy enough to look up as it’s needed.

    You don’t need to memorize the entire class structure of your projects. The “hot paths” get the most attention, and you’ll remember the most critical stuff as you work in a codebase. There’s lots of code that is basically “dark matter” - we know it’s there, and it’s doing something, but because we rarely review/modify it, it’s only important to understand its observable effects, not the precise way that it works.

    Your brain is basically like an LRU cache - the stuff that you touch a lot will stay loaded, and the stuff that you rarely use will get dropped. Embrace this property.




  • There are other reasons to use it. A major one is doing a “code review” of changes before committing, or even deciding to drop a chunk of code from a commit entirely (like a debug statement that no longer is necessary.)

    I’m all about frequent commits (and right-sized commits), but the functionality can still be beneficial even in those scenarios.

    I also don’t care if I have a broken commit. This turns up very quickly, and there is zero expectation that feature branches are always in a working/stable state. The expectation is that pending work gets off the local machine on a regular interval.









  • We used JIRA effectively at my last job, the things that made it work for us:

    • stop adding shitloads of required fields. Title, description, branch, priority (defaulted), status (defaulted), type (bug/feature). We might have had some others, but that was all I remember being required.
    • stop writing shitty descriptions: spend more time writing something that your co-worker can use. Respect their time enough to try to include enough detail for them to actually use the ticket. Be available to answer questions when they are assigned a ticket you wrote.
    • you don’t need extremely granular statuses: the functional role of the assignee is enough to determine what “state” it’s in, trying to codify a unidirectional flow of tickets is maddening and overly complicated. Work is messy, it flows back and forth, you do not need a “rejected by qa” status. Just leave it open and reassign to the developer with a comment. Managers find out when individuals are submitting half-assed work on a regular basis, you don’t need JIRA for that (unless you need metrics to fire them… different problem).

    I agree with the premise of the article, JIRA is a communication tool, not a management tool.