Monica

"click here" is usually weak, but not always

Mon, 18 May 2020 01:11:27 GMT

It's generally held among professional writers (and presumably some others) that constructs of the form "for more information click here", with "here" being a hyperlink, is not good style. It's far better, in general, to incorporate some clue about the content into the link -- "See the formatting help for more information", with "formatting help" being a link to documentation, provides more information at a glance and just reads less clunkily.

When answering questions on sites like Stack Exchange and Codidact, one sometimes wants to refer to another answer (for example to elaborate on it or disagree with a point made in it). I posted such an answer recently and used link text of "another answer" instead of "Joe's answer". If I had said "Joe's answer", somebody who's just read that answer would have context without having to go look. Someone who knows my general writing style asked me why I used the vaguer formation.

This is my general style on sites like these now, and I do actually have a reason. Two, actually, the more significant of which is caring about people's feelings.

On Stack Exchange, Codidact, TopAnswers, and presumably others with which I'm less familiar, users can change their display names. Using a name as text rather than an '@'-reference in a link can thus decay. I've seen too many posts that mention "Joe's answer" but there's no Joe evident on the page now, years after that text was written. So that's confusing and I try to be careful; some people change names frequently, leaving trails of dead references in their wakes.

But it's not just about avoiding confusion. For me this name-avoidant practice crystalized some years ago when a prominent SE user transitioned gender. I realized that old posts of mine (from before I was careful about this) now dead-named this person. Ouch! Also maybe dead-pronouned, though if you write posts in a gender-neutral way like I try to in such contexts, you can minimize that damage.

We don't know who's going to be someone different later. My desire to attribute properly is at odds with my desire to account for future changes that affect writing I might not actively maintain. For in-page references the post is right there; omitting the name in favor of a generic reference is not harmful and is more future-proof. For regular citations, I attribute by name because giving credit is important, and just do my best.

I know that people who transition -- even just names, let alone gender -- just have to deal with the fact that they had lives before and those references don't vanish. My friend Owen understands that sometimes we need to talk about Zoe. But sometimes we can do a small thing to alleviate a little bit of unnecessary frustration and not make people's lives more difficult. It seems worth doing in these cases where the cost of being mindful of these possibilities is small.

I don't do this everywhere. My blog, being more personal in nature, is more likely to refer to people by name, use gendered pronouns, and otherwise bake in current context. My blog isn't a public knowledge repository like Codidact is. We write differently for Wikipedia, Codidact, blogs, and email, and that's ok.

comments

seeking tools help (Madcap Flare, git, Jenkins, HTML)

Fri, 29 Mar 2019 21:34:13 GMT

Two of my recent tech-writing questions on Writing Stack Exchange currently have large bounties (from someone else). I'd really like answers to both of these, and if you're into that sort of thing and can answer in the next few days, you might be able to collect a bounty. I have some leads now on both, but not developed solutions.

Adding tags to documentation built in Flare? -- I want to be able to tag topics in our large doc set and have those tags show up on the individual pages, so that somebody could click on (say) "kerberos" and see all of the topics that we've tagged thus. Think of it like blog tags. I learned in a tweet this afternoon that Flare has something called "concept markers" that emit "see also" sections; that's on the right track, it sounds like, but I don't want see-also bloat so it'll need some modification.

How can I highlight changes in HTML output from Flare, based on branch diff? -- people can look at the source diff on BitBucket, but what I really want is for the built HTML to be marked where the diffs are somehow. It seems like there should be a way to take the git diffs, use them to locally modify the (XML) source to insert, I dunno, changebars or font color changes or something, and then do the build. So far I have a pointer to diff2html, which looks like it will produce an HTML report of the diffs separate from the built documentation.

Do any of my readers have relevant know-how?

comments

another misguided recruiter

Thu, 15 Mar 2018 14:51:21 GMT

Like many others, I get lots of unsolicited email from recruiters who claim to have read my LinkedIn profile and have a great opportunity for me. They're almost always wrong about both. But I usually skim the tech-writing ones when they arrive, to (maybe) learn a little about the state of the field.

The latest one, about a "fast-paced innovative team", started off generic, as most of them do. (Hint to recruiters: if you want me to respond, give me a reason to. I'm not actively looking; you have to show me something interesting.) But the list of responsibilities included "work with architecture and UX teams to understand how best to organize and present the documentation" -- hey, they have a UX team! That's unusual (in a positive way). I kept reading.

Then I got to the requirements, which included:

Experience with Cobol
Strong working knowledge of Microsoft Office

Ha ha, no.

Also, it's in New Jersey and the ad doesn't say anything about remote employees. Bzzt.

comments

short fiction

Mon, 21 Aug 2017 22:03:41 GMT

I wrote a short short story (~500 words) inspired by today's celestial events. Check it out on Universe Factory, the blog of the Worldbuilding Stack Exchange community.

I got the idea a few days ago and, well, I just had to.

comments

collaborative documentation

Mon, 22 May 2017 03:27:52 GMT

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.

comments

questions for the interviewer (tech writing)

Thu, 04 May 2017 02:01:05 GMT

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.

comments