Proposal: Documentation

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?

share
1  
Technical illustrations for example, would not be on-topic on Writers. – windspiral Mar 3 at 15:03
    
@Cebri good point. Maybe somebody will write some sample questions about that to flesh out the idea more. – Monica Cellio Mar 3 at 15:05
    
Yes, I do have a few questions in mind regarding technical illustration. Unfortunately I've already posted 5 questions, so I ran out of them. If anybody has a question about technical illustration, please share it! :-) I would also like to add that there are only a few related questions in graphicdesign.se (see: 1 and 2), and there is no specific tag for technical illustration, so there would be a place for it here. – windspiral Mar 3 at 15:36

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".

share
    
Some of those are on-topic on Writers, such as: writers.stackexchange.com/q/5139, writers.stackexchange.com/q/10681, writers.stackexchange.com/q/5136, writers.stackexchange.com/q/12440, writers.stackexchange.com/q/10052, writers.stackexchange.com/q/4976, writers.stackexchange.com/q/3785. "Writing" doesn't just mean putting the words on paper (well, into an editor). – Monica Cellio Jul 25 '16 at 15:38
1  
Don't forget there is a Research tag on Writing SE. So some question about researching and organizing data for writing are on topic there. – Mr Yolo Jul 26 '16 at 14:54
    
@MrYolo I looked at the Research tag on Writing SE and none of the Qs seemed to be relative to documentation. Of 76 (in 6 years) asked, 30 had 0 or 1 answers. Quite a few seemed more about research papers, than about researching as well. Not a good place to look for documentation related research answers, nor a place to find people with the knowledge to generate quality answers in that area. – Gypsy Spellweaver Jan 28 at 20:40

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.

share
1  
So the question is: should the people interested in a sub-topic of a site use that site (and help expand the topic), or should they make their own? SE has gone both ways; for example, databases, emacs, and web applications are all on topic on SO but have their own sites. But Java, Python, and git do not. Presumably the difference is, in part, whether there is actually a community around the specialty that won't use the more-general site. Is that true of tech writing? – Monica Cellio Jul 24 '16 at 21:38
    
Yes, it is true of tech writing. I go to TW meetups and conferences and so on. I don't participate in NaNoWriMo or go to open mic poetry nights. – Adam Wood Dec 12 '16 at 19:29
1  
@AdamWood I don't participate in NaNoWriMo but as a technical writer I use Writers. The question isn't just "is there a community" but "is there a community that can't/won't use the current site". Just in terms of topic density SE has gone both ways, as I said in my earlier comment, so I suspect the core question is: how tight and closed is the community that exists? – Monica Cellio Dec 12 '16 at 21:43
2  
It isn't just about where people will ask questions, but also about where people will answer questions. I haven't found any of the alternative SEs to be particularly helpful when asking tech-writing-specific questions. A docs.se would help gather in the STC and WriteTheDocs people (as well as other "non-affiliated" TWs, etc.) which would make it more valuable than the current hodgepodge of "this sorta fits." – Adam Wood Dec 12 '16 at 21:47
2  
I think @AdamWood makes a crucial point. It is not about where you can ask a question. It is about where can you assemble the right people to answer those questions. If you can assemble a critical mass of people who can provide good answer, the people with questions will find them. But people with answers are not going to hang out someplace where most of the questions are not relevant to their interests. – Mark Baker Dec 13 '16 at 0:09

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?

share
2  
Your characterization of technical writing is accurate. The focus is different than it is for fiction. And the focus for each of those is different than for academic writing, or journalism, or poetry. Not every question on a site will be of interest to every user on that site, but since technical writing has a home on Writers (I'm one of the top participants in that tag, BTW), I'm still left wondering how things would be better with a separate site. I'm not opposing this proposal,just confused. Meanwhile, while this proposal is baking, know that you can ask those questions there. – Monica Cellio Jul 25 '16 at 2:49
2  
@MonicaCellio: I am confused as to why you are still confused. I believe your questions have been adequately addressed here. To recap: 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. – David Vogel Jul 25 '16 at 12:47
1  
@DavidVogel your comment here has done more to clear things up than anything else I've seen. If that broader definition of "documentation" could be folded into the site description somehow, that'd be great. (I know you're working on that; I'm not nagging.) BTW, the downvote on one of the answers here is not mine. – Monica Cellio Jul 25 '16 at 12:52
    
Great! I am definitely looking to craft the site definition to highlight the distinctions. Thanks for your help in getting us to clarify this! – David Vogel Jul 25 '16 at 12:57

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.

share
    
It'd be great to see sample questions for this proposal that encompass those other areas. (Will this community really consider programming questions on-topic? Let's find out with some concrete examples.) . As they relate to writing, several of those are on-topic on Writers, so this proposal will distinguish itself in the differences, the things that aren't. I think most of the current sample questions would fit on Writers; having a bunch that wouldn't and that are high-scored will, I think, help this proposal advance. – Monica Cellio Dec 12 '16 at 21:40

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.

share
    
Software tools are on-topic on Writers; here are 100+ questions. Formatting conventions like GUI elements is on-topic too; here are two examples. If you have questions about these topics now, try asking them there. – Monica Cellio Dec 12 '16 at 21:36

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

share
    
An example of off-topic in writers.se and on topic here is this Q, although it should have been on-topic as it wasn't about UI design. Here, as about UI, or writing about UI, it would still be on-topic. As a further example, and to use your own logic, there's your own Q that has no answer, and only ~30 views, in over a month. This goes more to "where will the experts be to answer Q's?" more than "where can I ask my Q?" The latter could be "anywhere" the former seems to be "here." – Gypsy Spellweaver Jan 28 at 19:35
    
That question was closed as off-topic, but wouldn't a question that asks for "Any thoughts, standards, or good practices ..." be considered too broad on any site? – Scott Jan 28 at 20:33
    
@GypsySpellweaver I hadn't seen that first question, and I think the close-voters misunderstood the question. I've made an edit and am pushing to reopen it. As for my question, we don't actually know that this community has the answerers either. Perhaps somebody reading this here on A51 will answer and let us know where he came from. I just don't think the answer to unanswered on-topic questions on one site is to create a different site and say "ask here instead". I'd really like to know why the technical writers here want a separate site instead of participating on the existing one. – Monica Cellio Jan 28 at 23:39
1  
I'd suspect that the reason the TWs want a different site, if it is TWs behind this, is that the "culture" of Writing.SE just feels wrong. Not a TW, so can't say for sure, but in my mind technical writing (which is only part of documentation) is not the same as writing. One of the major differences is that for writers, it's a one-and-done job: the book is published and royalties accrue. Documentation, tied to real things as it is, is more of a cycle: document the thing now, thing changes, document the thing as it is now, repeat... That Q should be re-opened, maybe edited for perceptions. – Gypsy Spellweaver Jan 29 at 0:27
    
Writers has a broad scope, yes -- tech writing (which is why I joined the site in the first place), academic writing, journalism, and yes, fiction and other forms of creative writing, which because of demographics have more questions. Tech writing has some different concerns, but so do the others. Carving out a subset of a small site to make another site doesn't seem like the way to make a strong site. – Monica Cellio Jan 29 at 1:08
1  
@GypsySpellweaver: Very good point: Writers.SE feels like a very wrong place to be discussing documentation, at least to me. People with extremely diverse backgrounds end up working on documentation. I have no background in writing, save a few college courses, but I have found myself right at home doing it. I find it a great fit stemming from my experience teaching piano and programming. – David Vogel Jan 29 at 23:19

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:

  1. 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.

share
    
Thanks for the blog/AU links. The difference there seems to be beginners vs. advanced users (though I see that U&L has since changed that aspect of their scope). I totally understand beginners saying they need their own space; does that apply here? I think it'd be helpful for you to propose some of your sample questions here; I have thoughts on most of them but don't want to try to do specific comments on that here. – Monica Cellio Jan 29 at 1:30
1  
I've already posted a couple sample Qs here. The beginner/advanced split between Unix/AU is the obvious one. Another difference is cultural: AU users are more computer is tool and it's supposed to work, Unix users are frequently into the "guts" of the computer. In this case Writing is about the writing as a process, Documentation is more about using the writing as a tool, not the writing itself. Of course, there's also the differences between how they (TWs and authors) write in general. – Gypsy Spellweaver Jan 29 at 1:37

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .