A perpetual issue with any organization of scale is consistency in documentation. Spoilers: No I don't have a good solution, still working on that.
With wikis there's always an issue with of keeping content up to date, preventing stales and bit-rot, versioning content, and one of the largest nightmares:


Consistency in naming, format, organization, style, wording choices, and more.
Good docs are danged hard to pull off, and one should never underestimate the effort it takes to curate them and make them into something truly great.

Tech writers aren't nearly appreciated enough in our industry for being able to translate complexity into clarity.
A tech librarian that can curate entire systems of documentation, help to organize standards, and give clarity at a company level.

The type of influence, charisma, company-level thinking, and leadership that takes is insanely valuable.
Quite honestly I don't think it's entirely possible to have this level of organization in docs without some seriously talented writers.

Engineers are not nearly as amazing of writers as they like to believe themselves to be, and cultural issues aren't their forte.
Anyways, point being, documentation and writing is hard to get right and I'm not nearly at a level where I have a good answer for it.

• • •

Missing some Tweet in this thread? You can try to force a refresh

Keep Current with Brandon Weaver

Brandon Weaver Profile picture

Stay in touch and get notified when new unrolls are available from this author!

Read all threads

This Thread may be Removed Anytime!


Twitter may remove this content at anytime! Save it as PDF for later use!

Try unrolling a thread yourself!

how to unroll video
  1. Follow @ThreadReaderApp to mention us!

  2. From a Twitter thread mention us with a keyword "unroll"
@threadreaderapp unroll

Practice here first or read more on our help page!

More from @keystonelemur

13 Jan
Oh hey, I got a working Applicative!

Card = Struct.new(:rank, :suite)

.ap([*2..10, *%w(J Q K A)])
.ap(%w(S H D C))
New trick to thinking of them: unfolded list comprehensions. `liftA2` may be useful here too.
Anyways, normally I'd just use `flat_map -> map` here instead:

cards = [*2..10, *%w(J Q K A)]
.flat_map { |r| %w(S H D C)
.map { |s| Card[r.to_s, s] } }
Read 4 tweets
11 Jan
I may well go ahead and create "Red in Fantasyland - An Illustrated Adventure into Category Theory". The trick is I kinda don't want to mention it's a CT talk, nor that it covers monadic concepts, as that spoils the fun.
That all said this is a talk I really want to give eventually but don't have a firm enough understanding myself quite yet to make it.

If I do make it I'll likely independently record and release it later, and hope conferences like it.
So what's the story here?

In the land of the lemurs I introduced a figure called the "Escher Cat" who's based on M.C. Escher and the Cheshire Cat from Alice in Wonderland. Frequently Escher is with his dear friend Indigo.
Read 9 tweets
8 Jan
Neurodiverse folks: What styles of engineering interviews have you found work best for you? ...worst for you?

I'd love to hear your stories and opinions.

RT for reach?
I'll start:

Best: Projects, practical code, teaching, feature development, take-home assignments.

Worst: Algorithmic (CodeSignal, LeetCode), timed problems, whiteboards, reciting dictionary information, there's only one right answer questions.
I love problems which allow me to explore a space and have a conversation about what we're doing. Doubly so if the interviewer doesn't have one single answer they're looking for.

I especially enjoy if they're not severely time-boxed into hour segments. Very few think that fast.
Read 8 tweets
25 Aug 20
This question has come up a few times, and while I've answered it in promo materials internally I've never actually written out publicly:

What exactly is it that I do at Square, and how did I get to be a Staff Engineer?

General overview to start:

I help to lead the Ruby community at Square, and represent Square frequently in the industry through various forms of writing, conference speaking, recruiting, and more.
How did I get that position?:

I did a lot of Ruby, and I talked about it. I made opinions known, participated in designs frequently, mentored, and started emerging as a Ruby presence.

After some time a new team called Frameworks emerged and needed a Ruby lead.
Read 15 tweets

Did Thread Reader help you today?

Support us! We are indie developers!

This site is made by just two indie developers on a laptop doing marketing, support and development! Read more about the story.

Become a Premium Member ($3/month or $30/year) and get exclusive features!

Become Premium

Too expensive? Make a small donation by buying us coffee ($5) or help with server cost ($10)

Donate via Paypal Become our Patreon

Thank you for your support!

Follow Us on Twitter!