What is on-topic here and not on Writers?

Question

Proposal: Technical Communication

Technical writing is already on-topic on Writers.SE, with (currently) 225 questions on the technical-writing tag. What topics will this proposal cover that don't belong there?

Answer 1

Documentation involves writing, but it isn't writing.

It's interviewing, collating, taxonomizing, maintaining, fixing, updating, expanding, pruning, and more.

The writing aspects of technical writing and documentation surely are on-topic at Writers.SE.

But everything else? I wouldn't think so.

Writers.SE's Tour says the following is explicitly off-topic:

Anything not directly related to writing, copywriting, publishing or editing

And much of "documentation" is not "directly related to writing, copywriting, publishing or editing".

Answer 2

While technical writing is on topic on Writers (and I have answered a few of them), Writers is dominated by questions about fiction. While some of us do both, technical writing and fiction are very different crafts. To someone looking for a place to ask documentation specific questions, Writers is not likely to look like the right place to ask. Which also means that few professional tech writers are likely to be monitoring questions on Writers very often. Narrowing focus is important to creating a community of people serious about a subject. I think a mere 225 questions tagged technical writing is a sign that Writers has not attracted the tech comm community in significant numbers.

Answer 3

Documentation isn't easy to pigeon-hole ... but I know it when I see it. The profession includes people whose job it is to explain how things work at a deeper than superficial level. We write to inform, not persuade. We explain. We write clearly and concisely eschewing unnecessary adjectives and adverbs. Kurt Vonnegut said "Technical writers are trained to reveal almost nothing about themselves in their writings. This makes them freaks in the world of writers."

We are an audience. We have our own terminology and pet peeves. We deal with similar issues whether we are explaining software systems, tractors, or regulatory requirements. Most other technically-oriented communication forae are audience=specific - it would be nice to have one where all explainers are equal participants, regardless of subject matter or audience.

We would be nice to have a virtual place where we can get insights from associates who might have a slightly different perspective on things than our usual cohorts. After the Challenger disaster, one of the biggest problems NASA had to face was the institutional mindset that was shared by virtually everyone involved in the space program. It would be nice to have a diverse group to talk with.

My 2¢ - what do YOU think?

Answer 4

Writers.SE is not a place people are likely to look for information on the much wider subject of "documentation" which has become increasingly hard to even define due to it's cross-functional and rapidly changing nature. Creating effective documentation has grown past the traditional technical writing role and now involves other skill sets such as UX, information architecture, instructional design, graphic design, marketing, and programming.

Answer 5

The documentation community isn't huge, and it'd be a pity to split it unnecessarily. I know that answerers here think there's a big difference between this proposal and what's already on-topic on Writers, but I'm having trouble seeing it.

Today this proposal has 55 example questions. Two of them are off-topic on Writers; all the rest are on-topic. Now some of them would be closed (on any SE site) as too broad or primarily opinion-based or maybe unclear, but aside from the question about videos and the question asking whether examples need documentation, all of these questions are within the scope of an existing site.

In this comment on another answer I linked to several examples there. I encourage y'all to check out the technical-writing, api-documentation, research, indexing, software, and tools tags. (Hmm, it looks like we need an "examples" tag; we've got questions about them.)

Did the Writers community do something to offend y'all? Is there something we need to do to make you feel more welcome on a site where you could ask these questions today instead of waiting for the Area-51 gears to turn?

If this proposal really is substantially different, can we demonstrate that with the sample questions?

For reference, here's what the Area 51 FAQ says about site overlap:

In general, if a site makes sense as part of a bigger site, it's better to have one big site than a bunch of little niche sites. Site X should be subsumed by site Y if:

1. Almost all X questions are on-topic for site Y

2. If Y already exists, it already has a tag for X, and nobody is complaining

3. You're not creating such a big group that you don't have enough experts to answer all possible questions

4. There's a high probability that users of site Y would enjoy seeing the occasional question about X

Answer 6

Right now, Tech Writing questions end up in a few different places.

• Got a grammar/style question? Writing.se
• Need help with Sphinx or AsciiDoc? Stack Overflow
• Wondering how best to represent gui text in your instructional text? hrm...? Is it ex.se? or maybe graphicdesign.se? (I had a question about this bumped twice from SE to SE looking for a home...)

A single SE for all the different Docs/TechWriting things would be helpful. And yes, there is a huge community about these things.

Answer 7

Apologies in advance for suggestions being computer programming-centric, but the concepts ought to migrate well to many other industries. Here are some topics that

• What Best practices exist for inclusion of self-documenting code in the documentation standards of an organization?
• Should self-documenting code be required of coders?
• Should coders be checked on the revisioning of their inline comments as they modify the code?
• What methods should be used to capture screen shots for the documentation?
• How to create a video tutorial for the use of a product. I.e.: install a motherboard, assemble a baby crib, etc.
• What Best practices are there for updating documentation as products change? (I have purchased a product that had cosmetic upgrades, buttons moved and/or relabeled, yet the included documentation showed the old labels or positions in the pictures, and sometimes in the textual descriptions as well.)

As food for thought concerning the overlapping potential for Documentation.SE and Writing.SE, review this post in the SO blog and this Q on AU, both dealing with the overlap/difference between Unix.SE and AskUbuntu.SE.

As for the A51 FAQ on overlap:

4. There's a high probability that users of site Y would enjoy seeing the occasional question about X.

I really don't think users of Writing.SE would enjoy, benefit from, or contribute to documentation-based questions. They might have input when the subject includes technical aspects of writing in general, but they already seem to be put off by the technical writing tag. Traffic for that tag, lack thereof really, could suggest either that it's out of place there, or there's no traffic for documentation in general. When this goes Beta that question should be answered.

Answer 8

I think readers should also be considered.

I think a question like: "Where in your document is something mentioned/defined/described", or "Is this correct according to your documents and how/why" are on topic.

Not necessarily the author, anyone familiar with the document may answer such questions. Thus we communicate technicals.

I'm more familiar with the cryptography site. Its atmosphere is generally very academic, and we have a reference-request tag that's sometimes often used. So I think reference requests could be on-topic here.