Building the tools I document

I've come a long way as a self-taught developer. My software dev team is shorthanded at the moment, and the lead architect pinged me recently and said something along the lines of, "I know it's not in your job description, but you seem to pick up on stuff pretty quickly; want to make some deployment tools for us? If so, read up on ansible and the python jinja2 library."

And guess what? I'm getting it done! He gave the specs for what the tool should do*, I worked independently for the most part, occasionally checking in to make sure I was interpreting his specs correctly, read up on ansible, kubernetes, a few python modules (jinja2, argparse, and configparser), learned a lot about linux (our deployment environment), a few features of yaml and..... two weeks later I have a working script that is intended to be used by our devops team in production. The experience was such a contrast to my early Python days, when error messages were mysterious and frustrating; most of the time, I had an instinct for what was wrong and quickly debugged.

So at the moment, I don't have to ask, "when will the tool be ready to document, and what will it do?" Because I'm writing it. Which is a good thing, because the tool I'm coding will probably form about 30% of the documentation in the install/config guide I'm writing for our product.




*In its current form, the tool takes some yaml specs for kubernetes deployments, injects some configuration values into them using jinja2 (such as dynamic IPs for kubernetes services), copies those deployment specs to remote hosts using ansible, and deploys them via kubernetes' kubectl command-line interface.

Studying machine learning through Coursera

Since I document tech that involves machine learning and natural language processing, I've been meaning for a while to take Coursera's Machine Learning course. And I have a bit of bandwidth at work now, so that's what I'm doing.

It's great! I'll admit, I was doubtful if I'd understand anything since (shameful secret!) I never took calculus in high school; I opted for AP stats instead. At the time I was totally focused on studying classical music -- it never occurred to me I might wish one day I had.

Fortunately, the instructor is really, really good at going slow and reassuringly pointing out when we don't actually have to understand the calculus or stats he's talking about.  He's also really good a giving us an intuitive understanding of the purpose of a formula -- so, while I don't understand how to calculate a partial derivative for gradient descent, I do understand how taking the tangent of a curve gets us to take a step in the direction of steepest descent.

It also helps to have a spouse with a PhD in math; when the instructor mentioned the "line search" strategy for choosing step size but didn't go into details, my husband sketched out a 2-D representation that made intuitive sense to me.

I thought doing the homework would force me to understand the calculus/stats the teacher said we didn't need to understand...but it turns out that's not the case. Instead, so far it's more about learning the ins and outs of matrix math and of Octave, the programming language we're using. I'll admit, I'd be pretty lost without StackOverflow and the course wiki -- but when I see students posting the same questions I had, it reassures me that I'm somewhat on the right track.

This course got me thinking about how being totally unintimidated and getting by with "sorta understanding" is a valuable tech writer skill. Back in my student days, I wanted to master everything from the get-go. But teaching myself coding and learning about technology on the job taught me to grab at the big picture from the get-go instead, and fill in the confusing bits as I go. It's like my ability to read a book or a bunch of online info really quickly and connect the big-picture points first (something my engineering-trained spouse would never do).  That's not an approach that works for every field, but it sure works for a tech writer!

Another thing this course got me thinking about was how I love to learn. Again, back in my student days, there was so much to learn that I easily prioritized my strengths over less interesting material. Sure, math was OK, but there were plenty of more compelling subjects to study.  But as adults, we have less chance to learn new stuff (again, another reason I like being a tech writer -- I get to study!), and I find myself revisiting math with fresh appreciation. Maybe math is not my main talent, but who cares? I'm learning, and I love how my brain feels when that happens.

update
In the end, I did the homework and implemented gradient descent for linear regression and for logistic regression in Octave (with much online help). After that, I mostly audited the course and took notes. Some highlights I took away (probably I've mis-stated a bunch of stuff; I'd have to rewatch the videos to get it exactly right!):

• neural networks let you compute truth tables for logic operations like AND, OR, XNOR, bv varying the weights (thetas) of your inputs and then running the sigmoid function on the sum of the weighted inputs. In each hidden layer, you learn a new theta through forward propagation, i.e. through reapplying the sigmoid function(???)
• support vector machines are similar to logistic regression, with the addition of kernels (landmarks to which you measure the similarity, or distance, of your examples). In cost optimization, you compute the 'vector inner product'  (just a Pythagorean measure of length) between theta and training example, and try to maximize that distance, p, in order to get large margins between the examples and the decision boundary
• Unsupervised learning using k-means clustering was conceptually a lot simpler than I expected. You randomly initialize some k number of cluster (c) centroids (mu)  from your training set, compute the distances of the training points to the centroids, and classify them into clusters based on how far they are. Then you take the means of the distances in each cluster, place the centroids at those means, and recalculate the distances in order to come up with new clusters, then retake the means..etc.

My first REST API documentation

I've documented low-level hardware APIs, but never REST APIs -- I learned a ton working in Swagger for a Watson service API.

Looking back, it breaks down into two parts:

Learning about APIs, and learning about the Watson service.

Learning about REST APIs:

·        doc tutorials - For an introduction to fundamental API concepts and terminology, I found Tom Johnson's tutorial on documenting APIs invaluable-- he even had a post on Swagger specifically! (Tom's a prominent blogger in tech communications; in fact, I read his blog really intensively about 5 years ago when I decided to go into tech writing!) He helped me talk intelligently about endpoints, resources, query strings, etc.

·        building swaggger - Getting a local swagger build up and running was a task and a half due to the build structure (which has since been simplified, thankfully!). I leaned heavily on colleagues, but I was eventually able to get the build running on my Linux virtual machine -- though not, strangely, only my local Windows machine.  I must have spent days on this, yikes! But I wrote or updated 3 process docs on the subject, so hopefully the next person will have less pain.

·        modifying source code - Adding annotations into the source java files using @API annotations was not too difficult. But I ran into some bugs, and for the first time, posted and got answers about bugs on a developer forum(https://groups.google.com/forum/?fromgroups#!topic/swagger-swaggersocket/Xq7jCJS7WRc, https://groups.google.com/forum/?fromgroups#!topic/swagger-swaggersocket/ZCg4UZYYn08 ).

·        REST fundamentals - Learning to play around with the API forced me to learn some REST fundamentals too--when can I enter something in a parameter, versus typing a query string in the request URL? What syntax to use to  get parameter fields into the URL query strings? How can I discover whether a parameter field takes JSON or some other syntax? (answer--I think--is that there's not discoverable method; that's why you need the docs!)

Learning about the Watson service

My understanding of the resources I'm interacting with evolved quite substantially, though examining the source files for schemas and instance data, playing with the API, and most importantly, talking to the developers. I won't go into the details since the service isn't public yet, but I learned a great deal about type systems and entity/relationship modeling schemas.

L