littlelogs

Keep a social journal of your work progress as you make and learn things.

#docs

February 2017

josh
josh

I finished the #larder #api #docs today! It’s so fiddly to include all the code samples and stuff, but now it’s done. My next steps are to build the UI for developers to create and manage their client apps in Larder, and make sure the oauth “authorise” page is all styled nicely, then that’ll be done.

In other news, I added the #changemap search field autocomplete suggestions to the “add a new suggestion” form last week, so you have to click “no, my suggestion isn’t any of these” if there are matches. And since then we’ve had zero new suggestions. It definitely works, I tried it, but I guess nobody has a new idea that isn’t a duplicate. Success? 🤔

March 2016

ddbeck
ddbeck

My parents visited for a week and now I’m trying to put back some of my routine. It’s tough to keep to certain things, like logging, when you’ve got houseguests. Today I worked on outline for a new #docs section for work and got caught up on reading issues and email for the #pypug. Hoping to get a little more control over things during the weekend, since it should be pretty quiet around here.

February 2016

ddbeck
ddbeck

Last week, for work, I changed the way the #docs build works to remove some artifacts of a feature that #Sphinx has built in (search) that we don’t use (we use a separate full-text search engine instead). I discovered today that wasn’t such a bright idea, because it causes warnings on incremental development builds. So I had to fiddle with makefiles today to get that to behave a bit nicer. It’s a little crummy to have to re-fix a thing you thought was fixed.

After work, I got a lot done. I ripped a new blu-ray, read two #readme files for the #readablereadme project, made macaroni and cheese, and spent a little while figuring out Travis CI for #pypug.

January 2016

ddbeck
ddbeck

This will be short because I must have done something to my wrist yesterday, otherwise it wouldn’t be so sore. I’m trying to go easy on it. Ugh.

Today I managed to finish work on my Sphinx extension, though I gave up on a couple tests because mocking away parts of Sphinx got more complicated than the code under test. I’m looking forward to deploying that tomorrow.

#sphinx #docs #mysterypain

ddbeck
ddbeck

Today went way better than yesterday. For work, I fixed some navigation problems in the docs search that resulted from last week’s theme changes (a one-line fix, but a very interesting line nonetheless), among other things. In the evening, I managed to get to the post office, buy an annual travel insurance policy, buy train tickets to the airport, and review a pull request on the Python Packaging User Guide (hoping to actual merge something an evening this week). Finally, I read two readmes. A pretty productive day and evening.

#docs #insurance #travel #readme

ddbeck
ddbeck

Today was the kind of day where I think I got a lot done, but because I was rushing from one thing to the next, I’m not exactly sure what it was I did.

For work, I did a lot to improve the documentation’s documentation (so meta!), because my boss wanted to make some changes to the CSS. Since the last time I updated the docs’ docs, I had made a bunch of changes to the build system, so it was good to have someone ask a bunch of questions about how it worked—there were a lot of unstated assumptions in my initial notes.

Besides that, I went to the library, cleaned up the kitchen, and helped my parents decide on dates and pick out airfare to visit England in late February. I’m excited that they’re coming and kinda glad that I now have a concrete deadline to get the house cleaned up.

#docs

ddbeck
ddbeck

I guess that prep yesterday paid off, because today was very productive.

For work, I spent a while writing an extension for Sphinx, the documentation generator I use. Ironically, Sphinx is somewhat poorly documented itself, like the proverbial cobbler’s children. The last few times I’ve worked on this extension, I ended up only reading Sphinx and docutils source to figure out what it was doing. Today, I finally had a breakthrough and started generating the output I wanted to see in the first place.

In the evening, I submitted my first conference talk proposal. I’m fully prepared for my proposal to be rejected, but I’m glad I’m making some concrete progress on my goal to eventually speak at a conference.

#docs #python #docutils #sphinx #cfp

ddbeck
ddbeck

For work, I finally deployed some #docs changes that had been held up by unreviewed changes (I’m stuck using Subversion at work, so I find myself avoiding branches whenever possible). Not being able to deploy for a while is a good reminder of why it’s nice to be able to immediately do so multiple times a day, if needed.

After work, I reviewed a pull request for the Python packaging guide. It’s different being on the other side of that exchange than I am usually. I think I’m getting better about being confident with my feedback and knowing the difference between what I would write and what actually needs improvement.

#docs

ddbeck
ddbeck

Today I revised an old doc that I had written a long time ago—about the time I started my job. I always cringe a little bit at my old writing, but I was pleased that, in this case, the writing style was more or less fine. Instead, it was offering bad advice on a technical level. I’m OK with past me not knowing things that present me has since learned.

After work, I wrote a draft of an email to send out to my newsletter (primarily for friends and family) about my move to and life in the UK (I’ll link to it when it’s done). It had been a while since I wrote anything for that, because the habit completely fell apart when I got sick in November. 😷 One of a few habits I hope to repair soon.

#docs #writing

December 2015

ddbeck
ddbeck

Today I got to do a fun thing: delete some #docs. I love to prune old, irrelevant documentation. It’s nice to not have the burden of maintaining an old doc or, worse, letting it get increasingly out of date and unhelpful.

After work, I read a couple of #readme files and then turned my attention to Christmas preparation. I wrapped a few gifts and successfully tied the most pathetic looking bow around a box after trying and failing a bunch of times. Little victories.

ddbeck
ddbeck

Today, I spent some time editing artifacts in the #docs that reflect a change in the service that I document. We now have a service (dedicated servers) that we no longer offer to new customers, but have many existing customers who get to keep using it. So now I’m combing through the docs, trying to excise all the things that suggest that a customer may choose the no-longer offered service, but keep all things that talk about using the service. Lining up docs with versions of software is relatively easy, so it makes me wish the business itself were versioned too! 😃

In other news, I added a new issue to the Python Packaging User Guide specifically for a first-time contributor. I like what @yourfirstpr is doing, so I’m trying to do my part with a project in which I have a bit of administrative authority.

ddbeck
ddbeck

Hit the ground running this week by writing a long-overdue doc for adding an account to Mail on El Capitan. I don’t care for writing docs for GUI stuff because I hate taking screenshots. I had an epiphany—after the fact, of course—that I ought to record video as I write up the directions, then crop frames from the video for the screenshots. This would spare me from either forgetting to take a screenshot of an important step or having to take a screenshot of every single step. That’s something I can experiment with next time, which might get me a little more excited at the prospect.

After work, I got drinks with a couple of other writers here in Cambridge as a substitute for a canceled meetup in London. It was a lot of fun! Plus it was the kind of thing that made me feel like I’m a normal person who lives in Cambridge and not just an out of place American.

#docs

ddbeck
ddbeck

Today I didn’t produce much in the way of #docs, though I did produce a really detailed comment on a ticket describing an issue with the thing I meant to write about. The issue wasn’t a bug per se, though I suppose that would hinge on whether the problem was contrary to or in line with expected behavior. Anyway, investigating and reporting on the projects that I write about really fun, though I think it’s one of the most undervalued parts of tech writing. It doesn’t produce something for the portfolio that you can point at and say, “I made that.”

ddbeck
ddbeck

Wrote some docs about migrating MySQL databases between servers today. It was one of those things that I had been interrupted on repeatedly in the past couple of weeks, so I’m glad to finally have it off my list. I want to get better at avoiding situations like that. When a task or project stalls on me, in my mind it starts to grow and grow into a giant, insurmountable thing, slowing my progress even more. (But once I get passed something like that? Then I’m really moving!)

Lots of other stuff is going on, but I wanted to mention that progress continues on the as-yet-unnamed readme project. I want to express my love for what I’ve been thinking of as “README-only” projects (like this one or that one). It’s heartening to see a middle ground between large, durable documents (i.e., books) and small, ephemeral documents (i.e., blog posts).

#docs #mysql #readme

ddbeck
ddbeck

The Sun isn’t rising until almost 8 a.m. and it’s setting before 4 p.m. I’m starting to struggle with wakefulness, to say nothing of general motivation. I’m beginning to wonder about stronger alternatives to coffee.

For work, I revised some #docs to match modified UI strings and fixed some messed up formatting that I discovered last week. Maintenance work is important—readers notice if your docs are broken or stale—but it can be boring.

The brightest part of my day—no thanks to you, Sun—was seeing a tweet (with multiple favs/likes!) thanking me for coordinating work on packaging.python.org. I feel like I haven’t even done anything yet, so hopefully I’m going to really wow some folks as work continues.

josh
josh

Added a preview endpoint to the #littlelogs #api, so clients can preview the parsed HTML of a log before posting it. Handy for emulating the web’s preview/post flow. Also updated the #docs to mention this endpoint, and clarified the params needed to post and preview a log, and post a comment. They’re still pretty sparse though 😐

ddbeck
ddbeck

For work, I did some tidying up of a script that helps me manage some contextual help text. Previously, the script verified the appearance of certain notices based on other UI strings—a fragile, “stringly typed” situation. Today, I updated the script to check on proper database fields. Not a lot of writing today, but it was nice to exercise my programming skills a little.

Oh yeah, that announcement #blog post I wrote is up. Linked as promised.

Today I also did my first review of a contribution from a Python Packaging User Guide volunteer. It’s been a while since I’ve been an editor, so I had to be very careful to distinguish, for myself and for the contributor, between how I would write something and how the writing can be improved. They’re not the same thing! Lousy editors don’t know the difference—even if their own writing is excellent—and I don’t want to be a lousy editor.

#docs #python #php #editing #writing

ddbeck
ddbeck

Today I had a nice change of pace, starting a draft of a #blog post to announce the availability of a new version of a popular tool (it’ll probably go up in the next few days). I haven’t done that kind of writing in a while, so it was a little bit challenging to shift gears from the more muted style of the #docs to a more personal, relaxed style appropriate for a blog post. Identifying a “voice” of my own is something I struggle with a little bit generally, so I’m glad to have the chance to exercise it. (Though I think writing these #littlelogs may be helpful too—it’s like blogging, but lower pressure, and the audience feels supportive. Thanks, folks. :-)

ddbeck
ddbeck

Today I fixed up some #docs that had part of recent changes left behind in a #git stash. I feel like this is a mistake I’m making a little too routinely. I’m thinking about writing a pre-merge or pre-push hook to warn me if I have stashes outstanding. Though I think it would also be helpful if git stash insisted on a name, like git commit insists on a commit message.

ddbeck
ddbeck

Left this draft sitting here from last night. Whoops!

One of the things I did for work was to update some #docs that mentioned a configuration values for third-party service. The configuration values were out of date. It’s one of those things where those semantic web ideas would be nice to have in reality: instead of manually copying and pasting values from one doc into another, it’d be nice to just reference a portion of a page and have the tools take care of the rest.

After work, I went to my first Cambridge #Python meetup. It was a fun activity night, where we worked on the puzzles of the Python Challenge. People were quiet at first, but as we made progress it got livelier. I’m looking forward to the next one.

November 2015

ddbeck
ddbeck

Over the weekend, I did a bunch of literal housekeeping tasks away from the computer. I did read two more #readme files though.

For work: spent some more time on the #Drupal #docs, making sure they work with the latest version. Retesting documentation is important, but it’s as boring as can be—especially when it continues to work properly. 😴

For me: wrote some more of a contributor guide for that open source documentation project I’m helping out on. Planning to have something shiny to link to soon.

ddbeck
ddbeck

This is my first post to #littlelogs. I’m going to log the things I do and learn for a month and see how it goes.

For work: I revised some contextual #docs in response to #Drupal 8’s release. I ended up learning a bit about Drush. I really like the idea of controlling web-based tools with command-line interfaces.

For me: I started a rough draft of a contributor’s guide for an open-source project I’m helping out on. Hoping to ramp up work on that over the weekend. I read a couple more #readme files for my read-a-bunch-of-readmes project (which I don’t have a name for yet). I really liked the What is gulp? section of the #gulp readme. It’s not just a grab bag of nouns! It’s amazing how rare that is.

Finally, I was really wired for most of the afternoon. Lesson learned: don’t drink so much coffee on a mostly empty stomach.

July 2015

josh
josh

Updated the #api #docs at developer.exist.io to incorporate the oauth2 stuff. New plan is to make a bigger fuss about the write API (maybe some press/blogging) to get people to it, but still manually approve new clients for a while. #exist

June 2015

May 2015

josh
josh

Spent a lot of time copying #exist #docs from our current page into the new site, tidying them and adding some explanation in the process. Quite liking Slate, and I kinda like writing docs too.