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.

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.

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.

• Here's why you're not hiring the best and brightest: (Jeff Atwood) talks about making telecommuting work so that you really can hire the best employees, as opposed to the best employees willing to live in a particular location. I once applied for a telecommuting position at a company that seems to get it as far as that's concerned, and a lot of the stuff they do is reflected in this article.
• What do programmers care about? (20-minute video): Joel Spolsky (Stack Exchange, Fog Creek) talks to recruiters about how to recruit programmers. If you've read Joel On Software you already know a lot of what he has to say here, but I still found it interesting to watch.

Can you help? Somebody asked a question recently on Writers about guidelines and heuristics for when to use screen shots in technical documentation. The question isn't looking for opinions or what you, personally, do but, rather, formal guidelines along the lines of what GNOME does for its documentation. So far it's only attracting opinion answers. I, too, have opinions and practices that I follow, but I can't source them either and I'd like to see the question get a good answer.

Speaking of Writers, I wrote a little something about writing good API reference documentation (like Javadoc), based on advice I've given informally over and over again -- finally wrote some of it down in a public place. Feedback welcome.

I recently saw an article with interesting-seeming observations and analysis of Modern Orthodox Judaism. I'm not all that tuned into the MO community and can't evaluate its credibility from inside, but I found it an interesting read. If any of y'all would care to tell me where on the spectrum from "yup" to "WTF?!" this is from your perspective, I'd be interested.

Finally, a little something for those who use the text editor vim (which I gather is related to vi?):

.

Part of this meme:

LISP

The most valuable part of my education as a technical writer was my student internship with the Common LISP project. It was also either the first- or second-most important part of my education as a software developer. Yes yes, the classroom stuff was important and the software-engineering project course was essential for putting the pieces together, but this was the real world and the real world is far less tidy than the classroom.

I was brought on to help write the documentation for this then-in-development language. (Other varieties of LISP existed; this was an attempt to unify them.) But unlike all previous tech-writing work, this was for a thing that did not fully exist yet, and I was part of the ongoing design process. I was there in the (virtual) room with the lead designers, Guy Steele, Dave Moon and dozens of others big and small, and if my contributions had merit it didn't matter that I was an undergraduate with no real experience. On the ARPAnet nobody knows you're a dog undergrad. Mind, being an undergraduate with no real experience, I didn't necessarily have a lot of design ideas to contribute, but even then I was pretty good at catching inconsistencies and asking key questions. I learned to write software-interface documentation there, but even more importantly I learned to be part of a real software-development process, to ask questions even if they might seem "stupid", to argue for technical positions and support those arguments, and to be a full member of a team.

When I graduated and met more of the real world I would learn that it usually doesn't work like this. In a lot of places, tech writers are not part of the development process (and may not even be in the development department) and the attitude is that they can come in after the big boys are done developing the product. Phooey on that; this important early experience taught me that it doesn't have to be that way, and I have held firm on this in every place I've ever worked. If I hadn't had this early lesson, I might well have fled the field.

It is also because of the Common LISP project that I went into programmer documentation (and expanded from there). I wouldn't have pursued tech-writing jobs that were all about walking the menus in the UI and stepping through wizards and such; I want to look under the hood, understand what's there, and use that knowledge to help users. Building software development kits like I do now is exciting and nourishes my inner geek. When I went to college I hadn't even heard of technical writing (I went there to do computer science), but I came out as a technically-proficient writer who knows the good that is possible. I have Common LISP to thank for that.