17

Proposal: Technical Communication

NOTE: The site name has changed from "Documentation" to "Technical Communication"

I'd like for people to discuss the site description here.

Thanks!

1
  • 1
    A good site description should make justice to the name of the site. So let's make sure that "Technical Communication" is not only about documentation.
    – codeaviator
    Mar 8, 2017 at 21:35

8 Answers 8

Reset to default
8

Edit: Already implemented this change:

Documentation: Proposed Q&A site for information developers, technical communicators, writers, programmers, engineers, and others interested or engaged in documentation.

Edit2 (site name changed from "Documentation" to "Technical Communication"):

Since the name of the site has changed, there have been a variety of proposals for changing the description. Here's what I've come up with:

Proposed Q&A site for technical writers, content developers, engineers, scientists, and other professionals involved in the process of creating assets for documentation, education, and presentations of technical subjects.

Edit3 (3/19/17): After waiting for feedback/votes, I have decided to implement the above description.

15
  • The word documentation has a number of different connotations. Three that are significant to this question are: 1. The written material prepared by the creator of a product. 2. All material in any media that describes the product and is created by the creator of the product. 3. All material in any media created by anyone that describes the product. People do often use the term "the documentation" to mean #1, and thus to exclude videos or community content. But is that the meaning we want here, especially since that distinction seems to rest more on ownership and binding than quality or method.
    – user157502
    Jul 25, 2016 at 18:40
  • Do you have another title you would suggest? I like "documentation" because everyone has a sense of what it is, but it also encompasses quite a variety of things. For my own part, when I tell people "what I do" I just say "documentation," no matter what the actual job title is. Like most others in this industry I have to produce websites, videos, slide presentations, manuals, and so forth. We could call it "Technical Communications," but I think there is too much baggage there. Plus, I like just keeping it to 1 word.
    – David Vogel
    Jul 25, 2016 at 21:07
  • It is a bit of a problem. There is no really a clear umbrella term. "Documentation" tends to imply a particular format and ownership. "Technical communication" tends to imply a particular profession ("Technical Writer"). Neither of those limitation is appropriate to the new way in which technical information is communicated. The only option I can think of is to pick one of the above and then define it broadly. If I had thought of starting this, I would probably of picked "technical communication", but I don't think there is a compelling case to change it now. It's a toss up really.
    – user157502
    Jul 25, 2016 at 21:44
  • I don't think you'd want such a specific description/title that would be a turn-off to people. It needs to be something fairly open and descriptive, inviting to people to at least pop in for a look and perhaps contribute. That's my own humble opinion.
    – Daniel Anderson
    Jul 30, 2016 at 18:08
  • @DanielAnderson: Any suggestions on what changes to make?
    – David Vogel
    Jul 30, 2016 at 19:22
  • Oh, I don't know...What about "tech-know-logy talk"? I know, sounds stupid, huh? (grin) I think it's intriguing enough to pique peoples' attention but still not necessarily appropriate. Maybe "TechDocs"? I'm no good at coming up with names. I like the thought of something catchy, though.
    – Daniel Anderson
    Jul 30, 2016 at 20:41
  • @DanielAnderson: Actually I kind of like "TechDocs." Put it up as an answer & see if people vote for it!
    – David Vogel
    Jul 31, 2016 at 0:07
  • 1
    @DavidVogel: I also think, that "Documentation" is very specific and is quite limited in scope, because it seems to be related to writing. I suggest to open the scope and simply name it "Information Architecture". So "Documentation" is an instance of an "Information Architecture".
    – Stefan Jung
    Nov 17, 2016 at 12:03
  • @xephon: see reply to your answer above... "Information Architecture" is a different field. "Information Development" would make sense, so that might fix the inextricable link to writing that keeps popping up.
    – David Vogel
    Nov 20, 2016 at 11:36
  • As already mention, Docs are not part of IA. InfoDev is also really.... bad. "Information" means all sorts of things. Writing a non-fiction history book is "Developing Information." "Documentation" is the right choice.
    – Adam Michael Wood
    Dec 12, 2016 at 19:10
  • @AdamWood: Agreed on "information developer," but it has become somewhat in vogue which is why I put it in there. The redundancy of "technical communicator" and "technical writer" abrades my ears, so that was the reason for dropping it in front of "writers." I'll leave as is unless more passions start flaring, but I appreciate your input :)
    – David Vogel
    Dec 15, 2016 at 0:13
  • @DavidVogel As of edit #6: sounds like a solid description. I couldn't make it better if I knew how. I wonder about the lady that make the instructions for assembling the baby crib, though. Is that field likely to be on topic? How would she know that? The only "technology" in that is the screwdriver :). I suppose that the Help Center articles, which don't have to be so terse, can explain thing better to such as her.
    – Gypsy Spellweaver
    Mar 10, 2017 at 6:15
  • 2
    @GypsySpellweaver thanks! Even though I prefer the original name for the proposal, I think the name change and description will steer people in the right direction if they are looking for Q&A regarding the broad field of technical communications. Thus, our friends doing assembly instructions should find what they need here :)
    – David Vogel
    Mar 10, 2017 at 22:13
  • 2
    +1 Good job with the updated description. I think we are making good progress.
    – codeaviator
    Mar 11, 2017 at 1:44
  • 1
    The 3/19 edited version looks viable to me. Absent other voices and ideas, seems like it's worth keeping.
    – Gypsy Spellweaver
    Mar 26, 2017 at 1:15
4

Documentation is the best of all the not-quite-right options.

I like "Tech Writing," personally, because I think of myself as a "Technical Writer," not a "Documentation Writer" (or "Documentarian" - yikes). But lots of technical communication is not primarily written.

There are two problems I see with "Technical Communication":

  1. There is a professional organization called "Society for Technical Communication." They are nice and great and I don't want to say anything bad about them but: They represent (at least, here in SF Bay and Silicon Valley) a decidedly "legacy" approach to how to write docs and communicate about them. I don't want to see this new venue start with a bias toward (for example) XML/DITA/FrameMaker/etc over (for example) Markdown/rST/Sphinx/etc. (Both ends of the spectrum should be well represented)
  2. Technical communication, broadly defined, includes a lot of things that are not germane to what (I think/suspect/imagine) the purpose of a dedicated SE community would help with -- for example, marketing, technical content writing, etc.

There really needs to be an SE community/site focused on the (many, many) problems and issues of documentation. This include writing (style, grammar, structure), tooling (authoring, editing, publishing), and process ("DocOps"). Calling it "documentation" is the best way to communicate that this is the primary focus.

3

Just a few thoughts, which (after writing them) feel a bit like I'm bikeshedding...

information developers, technical communicators, writers, programmers, engineers, and others

I know a lot of people who write docs for a living. Most of them go by the title "Technical Writers." I don't know any of them who call themselves "information developers." Many are "technical communicators" on their resume but "technical writers" in person.

Also, because of where I live and my resume/background, I get several calls a day from recruiters trying to find people to write docs. 99/100 of these call the job "Technical Writer."

My opinion is that "technical writers" should be the first thing on this list. At the very least "writer" should not be orphaned without the modifier "technical" in front of it ("tech writer" is a thing in particular, and novelists are not likely interested in this SE).

If I had written the description, it would be:

Documentation: Proposed Q&A site about authoring, editing, developing, and publishing technical documentation. This site is for technical writers and related professionals.

4
  • 1
    Good point. (My business card says "information developer" but I say "technical writer" when talking to people, too.)
    – Monica Cellio
    Dec 12, 2016 at 21:45
  • Noted--thanks for the input. One of the main reasons for avoiding the title "technical writer" was to distinguish this proposal from the Writers SE site (which I had never even visited before proposing this). I would not have thought to look there for anything regarding what I do professionally which is indeed labeled "technical writing," as I am primarily grappling with the "technical" part and not the "writing" part. Thus, I was more likely to be groping around Stack Overflow looking for answers to my questions and thinking what a great idea it would be to have our own site...so here we are!
    – David Vogel
    Dec 15, 2016 at 1:26
  • And yet, technical writing is on-topic on Writers. I'm sorry you didn't know that before creating this proposal; if you'd be willing to share (on our meta) what we could do differently to make that more obvious, I'd appreciate it. Yes, fiction questions outnumber tech-writing questions by quite a bit, same as Java questions outnumber Lisp questions on SO, but that doesn't mean either site serves only the largest categories. Why can't we work together?
    – Monica Cellio
    Jan 27, 2017 at 3:53
  • 2
    Personally, I am interested in a site dedicated to this profession which talks about many issues that are not related to writing, such as has been discussed elsewhere on this proposal (UX, instructional design / eLearning, programming, etc.). I'm sticking with this field not because I like writing, but because I like the variety involved which requires a much broader skillset. My own background is in piano, composition, music teaching, and computer science. I happen to be able to write well, but more importantly, I know how to bring elements together to effectively communicate and teach.
    – David Vogel
    Jan 28, 2017 at 11:26
3

NOTE: At the time I'm writing this answer, the site description is currently:

Proposed Q&A site for information developers, technical writers, programmers, and engineers engaged in documentation.

As an outgrowth of discussion in the comment thread here, I propose to revise it to something like (additions emphasized, deletions struck out):

Proposed Q&A site for information developers, technical writers, programmers, scientists and engineers engaged in composing content for information-dense media such as documentation, presentations, white papers, reports, books, and journal articles.

4
  • Ok, based on the early downvote, sounds like there's disagreement over whether the site would just be for software docs, as opposed to technical communication more broadly?
    – hBy2Py
    Mar 7, 2017 at 4:14
  • 1
    I don't think this deserves a down vote, although how things work in Area 51 seems different than regular SE sites. I haven't read a lot of site descriptions, but this version does seem a bit heavy, or wordy, for most. That said, I think it really helps the description and I hope the Community Team and the originator of the proposal will check it out.
    – Gypsy Spellweaver
    Mar 7, 2017 at 4:27
  • 1
    @GypsySpellweaver <nod>, I'm relatively new to Area 51 myself, so I absolutely could be stepping on toes or kicking sand in the face of tradition on this. But, this is how one figures out how things are done on SE: blunder about until one starts getting more upvotes than down. :-P
    – hBy2Py
    Mar 7, 2017 at 4:29
  • 1
    Hi @Brian! Thanks for the input! I've been on vacation, so am just now seeing your posts. The description is indeed in need of amendment and I'll have to take a look at other proposals/sites to see what kind of length it should be.
    – David Vogel
    Mar 9, 2017 at 16:17
3

I feel that the title of "Documentation" is perfect. It is succsinct and descriptive. It is more inclusive than anything with "writer" in it could ever be.

The description of the site seems well formated and inclusive, including the programmers and engineers (the creators of that which needs documentation). To avoid the trap of thinking that documentation is only written, the description could be slightly modified to:

Documentation: Proposed Q&A site for information developers, technical communicators, writers, programmers, engineers, and others interested or engaged in documentation, in any format.

For the site to succeed it will need to attract a body of experienced people to provide answers to questions, and questions that will interest those experts, and entice them to spend time sharing their knowledge and experience. While the technical aspects of writing might be better dealt with in the Writers SE space, or even the English Languague and Usage SE space, this site will also have to deal with that, especially as it is often applied differently for documentation than for literature and reports.

The site name and description needs to suggest to potential experts, and querants, that this is the place to spend their time and energy. As insight into the importance of the questions, I recommend the SO blog post about Optimizing For Pearls, Not Sand.

Post Name-change

With the name change to Technical Communication, the site will need some changes to the site description. After stewing over it for a while, this is my contribution to the possible new version.

Proposed Q&A site for Technical Communicators and information developers, illustrators and editors, including scientists, engineers, researchers, software developers, and others who prepare content for reports, white papers, presentations, drawings, illustrations, instruction manuals, how-to guides, journal articles, specifications, grant proposals, and other supporting documents to communicate complex and technical information more easily.

I realize it is very wordy, and I'm sure there are better minds than mine that can condense that into something useful. I've already trimmed it as far as my skills will take it.

Note: About half of that is based on the entry for Technical Writers in the U.S. Dept. of Labor, Bureau of Labor Statistics, Occupational Outlook Handbook.

2
  • 1
    Yes, the description is in need of amendment. I'm just seeing all of these new posts today, as I'm on vacation. Yours seems a bit long, but has some good additions. I'll have to look at some other descriptions to see what the average length is.
    – David Vogel
    Mar 9, 2017 at 16:15
  • @DavidVogel Yes, it's long, too long in my view, but I'm at my limit for trimming it. Mostly because I'm not wanting to cut anyone out. I'm sure many areas would be included in "select" phrases, but I don't know them.
    – Gypsy Spellweaver
    Mar 9, 2017 at 18:45
0

Oh, I don't know...What about "TechDocs"? I'm no good at coming up with names. I like the thought of something catchy, though.

1
  • I gotta admit that I like "TechDocs" as an option, even though it's not quite right either. Seems nothing is exactly the answer. Now that the "Documentation" name has been abandoned in favor of Technical Communication maybe this can be revisited as the left-end of the domain name. techdocs.stackexchange.com.
    – Gypsy Spellweaver
    Mar 20, 2017 at 2:32
-4

I suggest a new name for the group: Information Architecture

"Documentation" is very specific and is quite limited in scope, because it seems to be related to writing. I suggest to open the scope and simply name it "Information Architecture". So a "Documentation" is a result of an "Information Architecture".

1
-4

Not sure whether it's ironic or hilarious, but the answer to "What should we name it" has been in your description the whole time- Technical Documentation**.

Simply calling it documentation is workable, unless of course you consider that I could be some conservationist who's working on documenting the mating habits of the Cuculidae (Cuckoo bird). How are you going to react to me asking about long & short outlines or how best to keep readers enticed by my documented findings? Personally I'm sure there would be ignorant criticisms and plenty of down-votes, but eventually someone would kindly explain to me that "this site is for documenting "technical stuff". At which point I would likely reply with "well why didn't you call it technical Documentation then?". "Where do I go now?"

I suppose I could submit a new documentation site idea, but I'd likely be told that a site called Documentation already exists. Afterwards I get upset and frustrated and yadda yadda you get the idea. Just be cognizant that documenting and documentation are not byproducts of the technical world, they apply to many things. If your intention is to have technical people discussing "Technical Documentation", then your site name needs to reflect your intent. Just my two cents, before taxes.

All that being said, I have two semi-related points I would like to address:

  1. Daniel Anderson suggested the name "TechDocs", which isn't a bad idea in the least bit, yet I see he'd received two down votes- Why? Normally I can find the answer in the comment associated with the down-vote, but there are no comments. The point I'd like to make here (since this is a documentation site) is those who down-vote someone's question or comment without providing a logical argument to the contrary, are of no use to the community.

  2. Similar to my last point, Stefan Eike suggested Information Architecture , and like Daniel Anderson's suggestion it was pretty good, yet it too received down-votes (which it shouldn't have). Fortunately a reason was provided this time. Unfortunately that reason is based on ignorance.

    (A) Saying "'Documentation" is not an instance of "Information Architecture'" is like saying 'building a car is not an instance of Mechanical Engineering' or 'building spaceships is not an instance of space travel'.

    (B) Justifying a statement by providing a link to Wikipedia is about as intelligent as holding up a tabloid and saying "see everyone... it's written right here in Purple crayon!" Wikipedia is opensource content with almost no editing restrictions. Any individual, knowledgeable or ignorant, can write anything they wish in that domain space.

I wrote a quick, yet adequate explanation of Information Architecture the other day. Here's a link for anyone interested: https://ux.stackexchange.com/a/104148/22680

6
  • Noted. Disagree. Exceptionally aggressive and verbose.
    – David Vogel
    Jan 27, 2017 at 16:29
  • That's great that you disagree, but with which part and why? You apparently skipped over the section where I wrote, "...those who down-vote someone's question or comment without providing a logical argument to the contrary, are of no use to the community."
    – Josh Campbell
    Jan 27, 2017 at 17:11
  • I did indeed read. First, you start off with a sentence that doesn't make any sense. I don't see what you are referring to there. Then you proceed to babble and insult. As concerns the issue at hand, I do not want to change the name to "Technical Documentation" because it is obvious when you are in the "Professional" section that you are not talking about documenting your walk around the block. Unless others press the issue, I won't be incorporating your suggestions. Consider well that concision is a virtue in this field, not to mention interpersonal communication skills.
    – David Vogel
    Jan 27, 2017 at 17:24
  • 1
    First: I don't envision this as a site for documentation exclusively for technical subjects, but about the technology of documentation. A user's manual for a toaster is documentation, but not very technical. Second: A down vote is a comment! It says "this post isn't useful to me." If I choose to add to that comment, then I might write more, if I think doing so is worth my time.
    – Gypsy Spellweaver
    Jan 28, 2017 at 18:38
  • "First: I don't envision this as a site for documentation exclusively for technical subjects, but about the technology of documentation. ..." I think you mean the 'Science/Structure of Documentation'. Otherwise known as Information Architecture.
    – Josh Campbell
    Jan 30, 2017 at 19:47
  • @JoshCampbell You may want to visit the latest Q for this proposal here. You may get another chance to champion your name change.
    – Gypsy Spellweaver
    Feb 18, 2017 at 3:13

You must log in to answer this question.

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