Blog: May 2017

Most of these posts were originally posted somewhere else and link to the originals. While this blog is not set up for comments, the original locations generally are, and I welcome comments there. Sorry for the inconvenience.

Social dancing and rejection

2017-05-28 from Community Building Stack Exchange

Tags: Society, SCA

A person who attends a weekly dance felt the group was becoming cliquish. In particular, this person would invite someone to dance, the person would decline (which the poster had no problem with), and then the person would dance the dance with someone else. The poster felt snubbed, said this happens more often than it used to, and wanted to know how to fix it.

I answered:

I used to be part of a weekly open dance group (renaissance dance). Two factors that were challenging for us were:

Some people were there to dance; others were there to socialize.
Among the people who were there to dance, some were there to "up their game" and some didn't care if things went wrong so long as people seemed to be having fun.

Dance involves other people -- at least a partner, but sometimes a set. If you're an experienced dancer who's focusing on dancing well, you might be frustrated if half the people in your set don't really know the dance and aren't in the right place at the right time (so the figure doesn't work). You might also find it not very much fun to have to guide your partner through the dance. I'm not saying any of this is right or wrong; I'm just saying that it happens. We saw it too. So if the person you're asking is much more advanced than you and is taking a more focused approach, and that person knows about the imbalance between the two of you, that person might decline your invitation.

The answer isn't to enforce an "everyone dances with everybody else" rule with dance cards to keep track and stuff. The answer is to find ways to help everybody meet their needs while encouraging a more open attitude. Here are some things we did: Read more…

Collaborative documentation

2017-05-21 from Dreamwidth

Tags: Tech

In the category of "things I posted elsewhere that I want to preserve here"...

Stack Overflow began a documentation project, based on the idea that good examples are the core of good documentation. But the project ran into some problems, so they're "rebooting" it. They're going to focus on a single topic (T-SQL) to start, and are doing some user research before diving in. (And I got some warm fuzzies from the fact that they cited my SEDE tutorial.) But it seemed like some important points about documentation could be missed, things that frustrated me when I participated in the beta of the first attempt, so I weighed in:

Documentation doesn't exist in a vacuum; it exists because there are real people with real needs, and there's also prior work.

Regardless of subject, there are a few types of documentation, and when it comes to structure one size does not fit all. For example, there's tutorial-style documentation (like that SEDE tutorial), which introduces concepts as needed (just enough, not too detailed) while walking the reader through a progression of examples, which might have iterative cycles. Another type of documentation is the complete, documented example -- something that the reader can download and run himself, that has good comments and then some doc wrapped around it. (I don't necessarily mean one big <code> block; sometimes it's better to go method by method, for example.) Reference implementations are an advanced form of the complete, documented example.

Then there's conceptual documentation, where you explain in more detail what's going on with the different kinds of JOIN, for instance. And -- perhaps less relevant here, but I'll include it anyway -- there's task-oriented documentation, where you provide step-by-step instructions for how to do something procedural like configure Kerberos. What distinguishes task documentation from documented examples is that there should be fewer decision points -- getting that DB web front end up and running might require 37 steps but they're pretty much always the same 37 steps. That's different from doc about how to optimize a query, where you might be teaching a skill instead of providing instructions.

There's also reference documentation -- think API reference or language spec here -- where the focus is on being complete but comparatively terse, but where examples are also valuable. (This is probably not going to be where our best bang for the buck is.)

My point in saying all that is: these different types of doc require different enabling structures. This doesn't need to be a ton of work, but it's something to think about. We probably want something more than "here's a textbox" and less than "here's the schema for our fancy XML representation" -- maybe we just need some templates? Maybe the question about what T-SQL doc has helped people will evoke answers that touch on structure and organization.

One general point: being able to organize content is important. (Even better if it can be sketched out early on, before all the pieces exist!) In Documentation 1.0 examples on a topic were ordered by votes; there's no way to do a progression that way. A tutorial can involve several examples or example fragments, and they need to be orderable. It also won't make much sense for them to be evaluated (e.g. by reviewers) in isolation, away from their surrounding context. That's great for an initial code review, but you also need to be able to answer the question "is this a good example of that thing we just explained?".

That last point, about organization, was my biggest frustration in trying to help with round one of this. Somebody requests examples of Topic X, and a bunch of people throw some code at it, and there's no coordination, no logical ordering, and no way to develop a progressive example. There were lots of people involved but it didn't feel like a collaborative effort. Good documentation requires a little more coordination than that, in my opinion.

A few short takes

2017-05-07 from Dreamwidth

Tags: Life

A friend of ours organized a private showing of Guardians of the Galaxy 2 for 60 or so of us this morning. (Apparently if you show up with enough people and don't take away a prime showing time, some theatres will actually do this. Our showing was at 10:30AM.) We haven't seen the first movie, but we wanted to go for the social aspect at least. Reading the plot synopsis of the first one on Wikipedia was sufficient to be able to follow this one. We probably missed some in-jokes, based on when people were laughing when we weren't, but that's ok. Groot (Groot II? Groot Jr?) was very entertaining, and they had some fun schtick with him in the credits. (Do watch the closing credits.)

Instead of tickets we were given buttons, each of which had one of the characters. I didn't know these characters in advance, so I traded my "blue guy" for a "cute raccoon". My comics-reading friends tolerate me anyway. :-)

In completely other news... one of those "Jewish things" you might occasionally hear about is pidyon haben, the redemption of the firstborn. The idea is that firstborn sons "should" serve in the temple, but God instead assigned that duty to the tribe of Levi. Nonetheless, if a woman's first-born child is a male, the father needs to "redeem" the child by paying a kohein (a priest, a subset of Levi) a few silver coins. There's a ritual for it, which I have never seen.

The torah commands this not just for sons but also for certain first-born livestock. I remember, back when I first learned about this, asking a friend who is a kohein, "so, in principle if I have livestock I can make you take my first-born goat instead of paying you for it?". Funny, but he was reluctant to give me his shipping address after that. But anyway, this is a real thing (pidyon peter chamor), but most of us don't have livestock and never see it. But it's a mitzvah. So I learned today that a local organization has purchased three pregnant donkeys with the specific goal of performing this mitzvah. Two have already given birth to female offspring (and this only applies to males), but there's still one more chance. This sounds neat. (I do not know if the baby donkey is required to be present for the transaction or if it stays on the farm.)

Readers who use source-control systems might be interested in this article about Git usability. The graph of the Git learning curve is spot-on. This is timely for me, as I am in charge of migrating our documentation group from SVN to Git and, in the process, establishing a sane branching model.

Thoughts on Jewish movements and where I belong

2017-05-04 from Dreamwidth

Tags: Judaism

In a locked post I talked about some things in the Reform movement that make me uncomfortable and noted that in many ways I'm better aligned with (Modern) Orthodox. I'm not republishing that post (which says some critical things about my own congregation), but some things came up in comments.

Somebody asked me why I wasn't considering the Conservative movement. I wrote:

The local scene there isn't great, but I would consider them. An unaffiliated traditional group would be great; we have a fledgling "partnership minyan" here that meets on Shabbat morning about once every 4-6 weeks. That's a start; it'd need to grow to be my primary or only community, but I'm certainly tracking it. (I haven't yet gone on Shabbat morning because of my minyan, though I did go to their megillah reading on Purim and came away with a good impression. I'd love to see this group do Friday-night stuff sometimes!)

We have "2.5" Conservative congregations in my neighborhood (a couple more out in the suburbs but that doesn't help). The "0.5" used to be Conservative and is currently unaffiliated, in part because their rabbi does intermarriages. (This is where my weekday minyan is.) That rabbi is leaving soon and they're hiring someone new, and I don't know what else they might change as part of that. So they could be viable in the future; too soon to tell. One of the others could also be a good home; I need to learn more about them. The third is not a good fit.

There's one theological question in my mind about Conservative in general (not these particular congregations), and I don't know if it's a fair question and/or how I would answer it. It is "why go halvies?" That is, if I believe that torah is from God at Sinai, then why not go all-in on Orthodox? And if I don't believe that, is there a reason to choose the Conservative movement or am I just shopping for a congregation I like and flavor doesn't matter? I know I'm not well-aligned with Reform; sorting out the rest will take some time.

And if I do believe this, as Conservative officially does too, then how should I feel about the levels of observance I do (and don't) see in congregations? I'm badly matched now; if I move I'd like to improve on that so I feel more like part of a community that cares about things like Shabbat and kashrut.

A downside about Orthodox is the gender-based restrictions. Not being able to lead/participate is why the parnership-minyan idea appeals to me. If I were a man I might already be in an Orthodox community, but as a woman (and one who is not a mother) I have some problems with that.

About Orthodoxy:

On Orthodox, I did mean the Modern Orthodox end of the spectrum, not the chareidi end. I think some of the chareidi extremists have gone off the derekh; how can you justify violating some mitzvot (like those about violence) to "protect" others (like their version of modesty)? I know there are lots of reasonable, respectable chareidim who aren't the ones making the news for assaulting people on the street or on buses, and I know that every group has extremists, but the chareidi extremists scare me and I don't want to be connected with them.

The Modern Orthodox Jews I know, though, seem to be more in the "my responsibilities are for myself and my family; why are other people's practices my concern if they don't hurt me, beyond educating anyone who seems open to such?" camp, and that's where I am. It's not my place to judge others for how or whether they observe halacha. If I think someone has intent and lacks some piece of knowledge -- doesn't know about the kashrut issue with such-and-such, for example -- I'll try to help out because he'll see it as help. And if somebody is doing something that endangers others, then of course I need to step in. But other people's relationships with God are their business, not mine.

In the Reform movement this approach runs in only one direction, by the way: it's improper to question other people's non-observance, but it seems to be ok to question their observance. People who think it's rude to criticize someone for intermarrying and raising the kids in both religions think nothing of criticizing me for not driving on Shabbat.

I'm sure there are members of Orthodox communities with observance that varies from the community, too. (For that matter, I don't currently meet their normative bar!) For me it's more about being among people who, generally, share my values and practices. Details and individual cases will always vary, but I'd like to share a baseline.

Questions for the interviewer (tech writing)

2017-05-03 from Dreamwidth

Tags: Tech, Work, Writing

Somebody on a tech-writing mailing list just asked what kinds of questions we tend to ask interviewers when we're interviewing for jobs. The person had already mentioned, specifically for hardware-related jobs:

Do you test the documentation? How?
How does legal review work (for things like liability)?
Availability of subject-matter experts for reviews?

Here's what I wrote in response:

My experience is in software, which might be different from hardware, but I always want to know:

How early and in what way are writers involved in development? Do writers participate in functional and design reviews? Do we have input into the user interface? Are we part of the team, or do we come in later, take what they've built, and document it?
Can I use the product? As much as I want?
What processes do both the dev and doc teams follow? (If they say "agile" there are more questions.) How is doc reviewed and by whom?
(How) do we make doc improvements that aren't directly tied to new features or bugs? (For example: larger reorganizations, improving indexing, adding runnable examples, tools improvements.)
(How) do you use source control for documentation?

That's off the top of my head, without digging out my notes from my last round of interviews.

So that's not a complete list either, but these are the kinds of things I tend to be thinking about. (I also try to find out if I have access to the source code, but since he was asking about hardware I didn't bring that up.)

I also want to know where the documentation group is placed, organizationally speaking, but I usually learn that indirectly.

In the comments, somebody wrote:

I don't think I've ever been involved in an Agile process that included Doc in the core team, but now that you raise the point, that's clearly a process failure.

I responded:

After my first (full, not intern) position where I was included as part of the core team, I've made it a hard requirement. Fortunately, since then, I've been able to insist -- meaning that (a) so far I can afford to be picky and (b) I have a very solid track record that means I don't get dismissed out of hand. People just starting out won't necessarily have those traits, but I always advise people to, at the very least, prefer companies where they'll be part of the core team if they're comparing offers.

The cost, to the doc person, of being included early is that you might have to redo some work and/or relearn some things, because until the feature is finished it can still change even though everybody agreed on a design. That happens -- QA discovers a performance problem that can be alleviated if you make this small change to the interface contract, or it turns out that this is inconsistent in some way that matters with that feature over there that's also going into this release, or whatever. (But I don't need to lecture you about this; you know how software-dev works.) So that's the cost, but against that there are huge benefits for the team. You alluded to UX benefits; specifically, doc people are already looking at things from the user perspective so they'll spot things or have suggestions that people deep in the implementation might not think of. In most organization, in my experience, there are a lot fewer writers than developers and a writer might be working with more than one dev team -- and therefore might know some of what's going on in that team over there that affects this one here. And a really big one IMO: trying to explain something is a really good way to find problems in it. You know this from rubber-ducking. So even if some work might have to be revised, I want a writer to be trying to explain the new thing early, early enough to make changes when those problems emerge. (A writer, in turn, learns to use a breadth-first approach and focus on key areas for early deep dives. If you're working like this you don't start at the beginning of the doc and work your way through it in order.)

Of course, I've too-rarely worked anywhere that had genuine professionals doing the documentation to begin with, which says something in and of itself.

That's true lots of places, yeah. And, to be fair, there are more than a few technical writers out there who don't know how to work in this kind of environment, who struggle with changing requirements, or who just want to start with a finished thing so they can take an orderly approach to the doc instead of helping to make the thing. It'd drive me nuts, but not everybody is like me. There's also a lot of poor "walk the menus" (or equivalent) documentation out there that makes people think that's all technical writers can do, and that doesn't help. I've had several senior developers and dev managers say to me, after some time working together, variations on "I had no idea that tech writers could do what you do" -- they'd never seen it before. I'm not saying this to brag; this is as much about mindset as it is about raw skills, after all. But it's something I've tried to imbue in every junior writer I've mentored over the years.