Updates from July, 2022 Toggle Comment Threads | Keyboard Shortcuts

  • ThomasPowell 9:25 am on July 5, 2022 Permalink | Reply
    Tags: billion laughs attack, owasp,   

    TIL https://en.wikipedia.org/wiki/Billion_laughs_attack

    Looks like Nokogiri is too simplistic (by default) to be affected, but the Psych parser in Ruby isn’t so lucky (if you expand to ruby objects, of course… it parses to a Psych object just fine.)

     
  • ThomasPowell 9:14 am on May 27, 2022 Permalink | Reply
    Tags:   

    Documentation vs. Useful Documentation 

    Extensive documentation is time-consuming, but relatively simple to create.

    USEFUL documentation is potentially time-consuming, and can be difficult to create as well.

    My approach to documentation (the tl;dr):

    1. Record what challenged me personally about a problem.
    2. Fill in background gaps.
    3. Add gory details as addendums or links (depending on stability of source documentation)
    4. Organize so that someone with very little time or attention span can find the important parts first (or linked). Highlight and callout important bits as your documentation platform allows.
    5. Publish it where your target audience will actually be (might be markdown in GitHub, might be a Confluence wiki, might be a Word doc/PDF sent for onboarding)
    6. Curate your documentation links and links to supplemental documentation as an iterative process.
    7. Iteratively edit your documentation as you revisit for your own purposes.

    Some challenges with creating useful documentation

    • The subject matter is too broad to cover in a clear and concise way.
    • You don’t know the subject well enough to document.
    • You’ve created documentation but the repository that it will be stored in will guarantee it is never found.
    • The subject to be documented undergoes regular changes that quickly make the documentation out of date.

    Subject matter too broad

    The solution to this is to take notes on specifically what challenged you. If you had to spend time discovering those things, someone else likely did too. By focusing on what was relative to you, you create potentially more useful documentation for others.

    You don’t know the subject well enough create useful documentation

    There is a sort of imposter syndrome lurking that assumes that everyone else knows more than you on the subject. While this may be true for people already experienced with a subject, it’s far less likely to be true of new members of the team, especially if they have less experience than you overall. The likelihood that there’s zero benefit to others is slim, and by documenting and explaining things, you solidify the knowledge your own mind.

    You’ve created documentation but it may not be found

    Document in a location where other documentation can be found. Or if you’re documenting code, document or link from the code or README. Create links to the docs from other docs.

    The subject of the documentation regularly undergoes changes

    Build time in the task to update documentation. I know it seems like you’re not “being productive”, but, in reality, adding/updating documentation can easily be more productive than the task that it is paired with. By documenting or updating documentation, you are magnifying your efforts across all of the people who come after you.

     
  • ThomasPowell 9:03 am on May 27, 2022 Permalink | Reply
    Tags:   

    If you’d like to get nothing done today as a software engineer, try to make programmatic sense out of the IANA Time Zone files

    https://www.iana.org/time-zones

     
c
Compose new post
j
Next post/Next comment
k
Previous post/Previous comment
r
Reply
e
Edit
o
Show/Hide comments
t
Go to top
l
Go to login
h
Show/Hide help
shift + esc
Cancel
%d bloggers like this: