/
it-s-a-feature-documenting-known-issues-and-product-shortcomings-ivana-devcic.json
30 lines (30 loc) · 2.12 KB
/
it-s-a-feature-documenting-known-issues-and-product-shortcomings-ivana-devcic.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
"abstract": "Imagine for a moment that documentation is the face of your product. How\nmuch concealer would you put on it?\n\nThe majority of people would likely agree that no product is ever\nperfect. When it comes to software, the jokes about bugs practically\nwrite themselves. Should the product documentation acknowledge this, or\nshould it cover up the imperfections? In some cases, the answer seems\nobvious, but what about those situations where there is a major known\nissue - or five? How should the person in charge of documentation\naddress this? Should they just stick a big warning into the release\nnotes, or point out the problem and offer a quick workaround in the\ndocumentation itself?\n\nThis is not only a content issue, but also a question of ethics. It is a\nchallenge that has come up time and again in my personal (albeit short)\ncareer as a technical writer, and I suspect many others have faced it,\ntoo.\n\nThis talk will look at some strategies that writers can rely on if they\ndecide this is an issue worth considering. Important aspects that will\nbe covered include:\n\n- the tone and language used when addressing product shortcomings\n- communication with stakeholders, product managers and other\n subject-matter experts\n- dealing with clunky or unintuitive UIs and workflows that are not\n officially recognized as issues, but are still impeding the user\n experience and understanding of the product\n",
"copyright_text": null,
"description": "",
"duration": 952,
"language": "eng",
"recorded": "2018-09-10",
"related_urls": [
{
"label": "Conference schedule",
"url": "http://www.writethedocs.org/conf/prague/2018/schedule/"
},
{
"label": "Conference video documentation",
"url": "http://www.writethedocs.org/videos/prague/2018/"
}
],
"speakers": [
"Ivana Devcic"
],
"tags": [],
"thumbnail_url": "https://i.ytimg.com/vi/r-6FycuppXg/maxresdefault.jpg",
"title": "\"It's a Feature\" - Documenting Known Issues and Product Shortcomings",
"videos": [
{
"type": "youtube",
"url": "https://www.youtube.com/watch?v=r-6FycuppXg"
}
]
}