Area 51 » Professional

The Technical Communication site didn't have enough activity during the beta and has been closed. You can download the data dump of all questions here.

252

followers

86 Example Questions (10 closed)

active newest votes

up vote 27 down vote

added by David Vogel Jul 25 '16 at 17:38

up vote 15 down vote

added by mbakeranalecta Jul 24 '16 at 17:57

What is the "curse of knowledge"? – Monica Cellio Jul 25 '16 at 2:51

en.wikipedia.org/wiki/Curse_of_knowledge – David Vogel Jul 25 '16 at 13:34

@MonicaCellio: Why would you ask something that can quickly be searched for? – David Vogel Jul 25 '16 at 17:41

This question is important in the documentation sphere. People ought to deal with it, but if they don't know it is a problem with known solutions, they will re-invent the wheel. Again. Maybe the question should be worded in terms of the definition, so people who have never heard of the term will identify with it. "If you are very familiar with the product, so that you have trouble remembering what a new user's problems are, what can you do to get that newbie input?" – Robert Echlin Aug 18 '16 at 19:07

Also very relevant in any technical scenario where communication is involved. Technical jargon can sometimes become a language barrier for any audience not versed in a particular field or topic. – codeaviator Mar 26 '17 at 23:06

show 1 more improvement suggestion

up vote 13 down vote

added by mbakeranalecta Jul 24 '16 at 17:59

closed as not constructive by curiousdannii, Zizouz212, Ramon Melo, JonMark Perry, Monica Cellio Jun 4 '17 at 22:38

This question is not a good fit to our Q&A format. We expect answers to generally involve facts, references, or specific expertise; this question will likely solicit opinion, debate, arguments, polling, or extended discussion.

Don't you think this question would be disqualified as being subjective? Or is the purpose of the documentation SX site to encourage discussion about where specific tools and technologies could be used, and specific industries that prevent moving forward? – Tony Chung Jul 29 '16 at 20:51

It should not be disqualified as being subjective if you can provide evidence to support an answer. PDFs are a relevant format if people use them (even if there are alternatives). They are irrelevant if people don't use them. Opinion can mean taste or it can be an assumption about something that can be established factually. Some questions are clearly about taste. Some ask about matters of fact that may or may not be testable. Even if you outlaw matters of fact that are not testable, who is in a position to know for certain that they are not testable? – mbakeranalecta Jul 29 '16 at 21:51

up vote 13 down vote

added by Trilarion Aug 30 '16 at 11:56

As written I think this would be closed as primarily opinion-based (a reason not available on Area 51 or I'd so vote), but you could instead ask about important factors/trade-offs in making the decision. – Monica Cellio Sep 25 '16 at 18:08

I agree with the careful wording in order to make the question answerable. However I also agree that these popular (maybe beginner) questions have a value and it's worthwhile trying to make them fly. – Trilarion Jan 31 '17 at 8:39

up vote 12 down vote

added by Federgraf Sep 15 '16 at 9:06

As more adaptive and assistive technologies become available, and as more organisations, private and public, institute requirements for meeting accessibility standards, this will become increasingly important. Definitely on-topic! – RandomThought Apr 11 '17 at 3:42

up vote 12 down vote

added by Bad Pitt Sep 19 '16 at 17:57

up vote 12 down vote

added by Scribblemacher Nov 17 '16 at 12:36

up vote 11 down vote

added by mbakeranalecta Jul 24 '16 at 17:53

up vote 11 down vote

added by WorkingWriter Jul 25 '16 at 14:40

up vote 11 down vote

added by David Vogel Jul 27 '16 at 20:57

Sorry, could you clarify please why is `nuclear safety' in curly brackets? – Alex_Bender Jul 28 '16 at 13:18

I was following the style used by @warren. It is supposed to denote a variable indicating that another subject could be substituted. After just now looking at some of the other proposals, it doesn't look standard. @warren, care to comment? Thanks! – David Vogel Jul 28 '16 at 13:36

@Alex_Bender - there are a few ways to signify a question is a type and not an actual example. You can put interchangeable terms into angle brackets, square brackets, or curly braces. So, "Why was {General Patton} never diagnosed with {dyslexia}?" shows a type question that helps to define a category of question that can be asked. The item in the call-out is basically a placeholder / the question is a template. – warren Jul 28 '16 at 17:19

So this question is not a question for people to answer, it is a template to help people write {appropriate} questions? Pick one of a superset of the following two sets: (better, simpler, more, readable, clear, boring, repetitious, classic, old-school, easy, unnecessary) [one set supports this question, one set does not] [I am not completely sure which examples in this double set support the question and which do not] – Robert Echlin Aug 18 '16 at 19:16

Yes, we're coming up with example questions that would be asked on the site. To quote the robot at the bottom of the page, "We want to find the best example questions. Discussing whether questions are on-topic or off-topic helps figure out what the site is about, and, more importantly, what it's not about." – David Vogel Aug 18 '16 at 19:56

up vote 11 down vote

added by David Vogel, edited by warren Sep 15 '16 at 14:00

up vote 11 down vote

added by Robert Echlin Aug 18 '16 at 19:45

up vote 11 down vote

added by Alexis Dufrenoy Nov 8 '16 at 14:01

up vote 10 down vote

added by mbakeranalecta Jul 24 '16 at 17:56

Wouldn't this be closed as primarily opinion-based? There's no global right or wrong answer to this question. – Monica Cellio Jul 25 '16 at 2:50

I think the answer to this depends on your product environment. There are a number of variables -- Intellectual property, licensing, versioning, and even whether your typical customer has access to the open web while using the product. There might not be a Yes/No answer to this question, but discussion can surely help to clarify the issues. – cud Jul 25 '16 at 8:35

I have edited to try to make it clear that there are indeed measurable facts that go into an answer to this question and voted to reopen. Indeed, the politics are puzzling. – mbakeranalecta Jul 25 '16 at 23:56

I voted to reopen too. It is a good question. – David Vogel Jul 26 '16 at 0:00

up vote 10 down vote

added by cud Jul 25 '16 at 8:30

closed as not a real question by Zizouz212, Gilles, Robert Cartaino Feb 13 '17 at 20:20

It's difficult to tell what is being asked here. This question is ambiguous, vague, incomplete, overly broad, or rhetorical and cannot be reasonably answered in its current form.

this is too broad of a question – DForck42 Nov 28 '16 at 19:17

Haven't looked into it, but seems like a Q for the Internet of Things SE site. – RandomThought Jan 29 '17 at 1:02

I'm not sure this is strictly for an IoT site. There are specifics about documentation that need to be addressed. We have current methodology for delivery, planning, structure, organization... How must these be adapted to the requirements of IoT? You need a documentation background to have that discussion -- I see little contribution in strict IoT discussions from people with such a background. Yes, this discussion needs to happen in an IoT site, but it also needs to happen in a doc site. – cud Jan 29 '17 at 12:25

up vote 10 down vote

added by warren Jul 25 '16 at 15:07

up vote 10 down vote

added by warren Jul 25 '16 at 15:11

up vote 10 down vote

added by David Vogel, edited by warren Jul 26 '16 at 13:33

up vote 10 down vote

added by Alex_Bender Jul 27 '16 at 14:31

Could you clarify this? I'm not sure what the question means. It seems to imply that it is possible to automate the entire documentation process. – David Vogel Jul 27 '16 at 22:56

I'm talking about something like Sphinx for Python. It can generate documentation from code, which annotated in some defined way. – Alex_Bender Jul 28 '16 at 13:16

OK, it is confusing the way it is worded. Also, the questions are supposed to be narrow so they don't elicit extended discussion, requests for clarification, and so forth. Maybe you could edit the question to something like "Is it efficient to use Sphinx for generating all of the documentation for a project or would it be more efficient to do it manually?" – David Vogel Jul 28 '16 at 13:42

Thank you David – Alex_Bender Jul 28 '16 at 15:51

up vote 10 down vote

added by David Vogel Jul 27 '16 at 22:46

up vote 10 down vote

added by KimN Aug 3 '16 at 15:17

up vote 10 down vote

added by Robert Echlin Aug 18 '16 at 19:49

Why? 1: Because the boss said so. 2: There may be other constraints that the 2 techpubs dept. members don't know, including requirements from clients or external users, or integration with other projects. Maybe just to keep the sales crew happy with something they understand. 3: Any confusion, refer to #1. – RandomThought Mar 20 '17 at 2:41

up vote 10 down vote

added by Tom Johnson Sep 6 '16 at 5:04

up vote 10 down vote

added by Tom Johnson Sep 6 '16 at 5:07

up vote 10 down vote

added by Tom Johnson Sep 6 '16 at 5:08

There's always time to do what's important. The question is how to make the process a priority, not how to enforce it. – RandomThought Apr 9 '17 at 2:09

up vote 10 down vote

added by Bence Kaulics Dec 2 '16 at 9:23

up vote 10 down vote

added by Adam Wood Dec 12 '16 at 21:50

up vote 10 down vote

added by Adam Wood Dec 12 '16 at 21:53

up vote 10 down vote

added by Bence Kaulics Dec 22 '16 at 9:51

up vote 10 down vote

added by Tariq Ali Feb 4 '17 at 22:04

up vote 10 down vote

added by RandomThought Feb 24 '17 at 6:26

up vote 10 down vote

added by codeaviator Mar 26 '17 at 2:00

up vote 9 down vote

added by mbakeranalecta Jul 24 '16 at 17:54

closed as not constructive by curiousdannii, Zizouz212, Robert Cartaino Feb 13 '17 at 20:18

This recent feature of SO is the impetus for this site. I wasn't aware that we could create a whole site of our own just like SO and, surprisingly, there wasn't already one in existence. – David Vogel Jul 24 '16 at 18:41

up vote 9 down vote

added by Sarah Maddox Jul 25 '16 at 5:03

up vote 9 down vote

added by warren Jul 25 '16 at 15:10

Related (more specific): writers.stackexchange.com/q/5139/1993 – Monica Cellio Dec 12 '16 at 21:50

up vote 9 down vote

added by Monica Cellio Aug 16 '16 at 3:06

Given more space, the question would add: no budget for tools that cost money, free tools potentially ok, but a lot of people are already not only familiar with but experts in the existing tool. Solving the problem with the existing tool would be ideal; migrating could be ok if the experience is similar & some tools knowledge/skills can transfer. – Monica Cellio Aug 16 '16 at 3:08

up vote 9 down vote

added by Robert Echlin Aug 18 '16 at 19:34

up vote 9 down vote

added by Trilarion Aug 30 '16 at 11:57

up vote 9 down vote

added by MechtEngineer Nov 5 '16 at 6:56

You can use known placeholders name, such as example.com. Also you can make them italic, put them in angle brackets, make them pseudo-variables like %username%. – Stanislav Kralin May 13 '17 at 8:54