And you are here why?

/via https://theprocessconsultant.com/process-documentation/ If you’re good (or lucky), you actually know — and have documented — what your system looks like. Then again, do you? Really? For example, what happens when you’re on-boarding somebody — is there a process by which they’re brought up to speed? If “ throw them in the deep end ” is what you do, well, I guarantee you that there are vast swathes of the systems that are equally “deep-end”-ish to you! Let’s take this a bit further, and think about the different ways in which you probably  don’t  know your system well (or well-enough. Either can be a killer!) 1.  Legacy : What about all the legacy code that you’ve got? Remember,  legacy includes all the code that you’re written in the past, the skills that you’re not actively exercising, the components that were written by ex-employees , etc! Is that accurate? What’s more, every time somebody does something to legacy stuff,  is the test coverage ...

There are  so  many factors that go into success — market, product, requirements, customers, oh, the list goes on. That said, there are a couple of things that you  must  do to make sure that  failure  isn’t guaranteed. The following list isn’t exhaustive, but it is, most definitely, table-stakes these days for how you should structure your APIs. 1. Respect Every API : You don’t really know which API is going to be used, and which one isn’t. Murphy’s law pretty much guarantees that the throwaway buggy one that you put out there is going to be  the  one that causes you the most trouble. And  Hyrum’s law  will ensure that that shitty implementation will be made concrete, and you’ll never get rid of it. 2. Be Obvious : Make sure that there are no surprises. No unexpected side-effects, no behavior that isn’t documented. Seems like such a small thing, but, in the end, it’s the side-effects and/or hidden features that will get you. 3. ...

I know, this is kinda ridiculous. Just for argument’s sake though, let’s pretend that you’ve got your act down — you built your product it’s actually selling, and you’ve got $$$. You’ve achieved that elusive  Product/Market Fit , where the thing you’re building is the thing that people want, and are willing to pay for. Product/Market Fit Evolves The issue with having achieved Product/Market Fit is that things change. People might be willing to pay for your widget today, but will that be true  tomorrow ? After all, • Competition  might bring other players into the market, who could sell the same thing for less. After all, they’ve already seen what works, don’t need to recoup R&D like you did, etc. • Customer needs evolve , heck, you might be the one that’s causing them to ask for more! Are you prepared to satisfy those needs? There are other reasons why what works today might not work tomorrow (market gets tapped out, regulatory changes, etc.). The point ...

“ Great documentation builds trust, differentiates you from your competition, and provides marketing value . ” Here, Diana is talking about the good stuff, the stuff that you actually enjoy reading, that you can rely on, and that you might actually extol. (Yes, it exists!  Stripe’s docs  are a great example). /via http://geek-and-poke.com/ Unfortunately, in most of our world, documentation is one of those things that is frequently an afterthought. Or worse, left to the  #TechBros . “The code is the documentation”  — #CowboyDeveloper Documenting  what  the code does can be remarkably useful for somebody modifying the code, but  is close to useless for somebody that wants to use the system, and doesn’t give a s**t about the underlying code . The Components Product documentation should have three clear components • Concepts : An introduction to the system, that provides an understanding of its overall purpose , the ideas and concepts emb...

/via http://geekandpoke.typepad.com/geekandpoke/2010/03/simply-explained-entropy.html The two different times when your code made sense to you 1) When you wrote it 2) (Later) When you spent hours pouring over it, and figured out — again — what it does. The amazing thing is, it tends to be blindingly obvious each time you figure it out. The even more amazing thing is how you didn’t add any documentation, even after -2-, because   this   time you were sure you had it figured out.

So yeah, per the AWS ECR docs , EC2 stores your images in S3.  What they don't tell you, unless you really go hunting , is that This isn't just a feature, but something really relevant to you because  You'll need to be able to get to S3 to push/pull image Which may not matter till you, till you end up spending five hours trying to figure out WhyTF your wholly private VPC can't pull images from ECR. Oh yes, you got the NAT gateway set up, and can do pretty much everything  else (including pulling from DockerHub ), but not from ECR. Sigh. It's good to know that the quality of missing information in AWS Documentation remains as high as it used to be. P.S. The fix is easy - a VPCE.  But that's once you know the answer...

Erlang documentation always makes sense ex post facto .  Rarely, if ever, ex ante . Mind you, its a lot better than the usual lot ...

All discussions about MongoDB will eventually include the phrase " It's there in the documentation " Corollary All sins are forgiven if they are documented beforehand Note Seriously, I don't care how bloody carefully it is documented, the default behavior of a database should not include silently losing information.