Стил и стандарти в техническото писане. Тази презентация ще ви запознае с основните стандарти за писане на техническа документация в софтуерния бранш. Защо изобщо ни трябват стандарти и какво налага прилагането на стилови правила?

1. Стил и стандарти
Ко? Не! … ама по-добре ДА
Бранимира Димитрова
Йордан Георгиев
Ралица Цонева
© 2013 VMware Inc. All rights reserved

2. Инструкция за експлоатация







2
Как се предава информацията?
W*F is standard?
Защо са ни стандарти и какво е Style guide?
Основни изисквания към документацията
Какво е минимализъм и topic based writing?
Какво е DITA като стандарт?
Примери за правила и как ги прилагаме

3. Как се предава информацията?
Ами зависи...
Всяка индустрия има правила
Кой е потребителят?
Какво искаме да му кажем?
Колко ще инвестираме?
3

4. Текст
4

5. Графика
5

6. Видео
 VMware Technical Publications Video Channel
6

7. Текст + графика
7

8. 8

9. Опит за дефиниция

Стандартите са документи, разработени с консенсус на основата на обединяване на резултатите от науката, технологиите и производствения опит.

Стандартите са общопризнати правила и норми и може да включват подробни технически спецификации (характеристики и изисквания към продуктите), процедури за производство, методи за изпитване и оценяване на съответствието.

Когато се прилагат стандарти, се постига по-добра ефективност при производството на продуктите и подобряване на услугите и се удовлетворяват в по-голяма степен очакванията на потребителите и клиентите. За да се повиши доверието на обществото
Общоприети правила, които
се следват от всички с цел
уеднаквяване на крайния
продукт и повишаване на
качеството.
към стандартите, е необходимо при тяхното разработване и обсъждане да участват повече заинтересувани от стандартизацията страни.

Стандартите се разработват, преработват, изменят, коригират или отменят в зависимост от новостите в развитието на науката и технологиите. За да може да се отговори на потребностите на обществото и пазара, непрекъснато расте необходимостта от
разработване на стандарти.

Стандартите са пряко свързани както с начина ни на живот, така и с условията на работа, като все по-често обхващат и услугите. Много често, дори когато не го осъзнаваме, стандартите правят живота ни по-безопасен, по-здравословен и по-лесен. Те са
средство за информация, улесняват търговията и общуването между партньорите.

Стандартите подпомагат икономическото развитие, което е в полза на цялото общество.
Последните изследвания показват, че с разработване, приемане и прилагане на стандартите в развитите европейски страни се спестяват около 15 милиарда евро за година за изследване и разработване на нови технологии за производство.
/Български институт по стандартизация/
9

10. “The good thing about standards is that
there are so many to choose from.”
Andrew Tanenbaum
10

11. Какво и трябва на една документация?
 Да е лесна за използване (Usable)
• Ориентирана към целта
• Don’t tell me how it works, tell me how to use it.
• Вярна
• Be sure you are right, then go ahead.
• Пълна, но не претрупана
• A successful book is not made of what is in it, but what is left out of it – Mark Twain
11

12. Какво и трябва на една документация?
 Да е лесна за разбиране (Understandable)
• Ясна
• Easy reading is damn hard writing
• Конкретна
• “… the feeling at the end of the page when you realize you don’t know what you just
read.”
• С консистентен стил
• Style is the outside of content, and content is the inside of the style.
12

13. Какво и трябва на една документация?
 Лесна за намиране (Easy to find)
• Добре организирана
• ….nothing constructive can evolve from chaos except order.
• Откриваема информация
• Knowledge is of two kinds. We know a subject ourselves, or we know where we can
find information upon it.
• Визуално ефективна
• Art does not reproduce the invisible; rather it makes it visible.
13

14. Какво е Style Guide
 100 = 1 ???
14

15. Що, бе, Миме?




Потребителят знае какво да очаква
Има представа къде да търси съответната информация
Не се налага да „разгадава“ стиловете
Не се налага да чете излишна информация
 Безпроблемно ползване на продукта=CA$H
15

16. Хубаво, ама много зор, бе!




16
Изисква се време за създаването
Изисква се време за осъвременяването на стандарта
Хората трябва да се обучават непрекъснато
Творчеството не е на почит?

17. Какво е минимализъм в техническата документация?
 Предоставяне само на необходимото
 Премахване на несъществената информация
 Фокус върху осъществяване на целите на потребителя, а не
върху възможностите на продукта
 Подпомагане на потребителя за извършването на задача или
решаването на проблем
 Предоставяне на необходимата информация на правилното
място
17

18. Topic-based writing
 Тopic – самостоятелна единица информация
 Темата има заглавие и съдържание
 Една тема съдържа една самостоятелна процедура, концепция
или справочна информация
18

19. DITA като стандарт за topic-based writing
 DITA – Darwin Information Typing Architecture
 DITA се основава на принципите на минимализма и
тематичното писане
 DITA изпозлва семантични XML елементи
19

20. Видове DITA topics
 Task topic – описва една процедура (как да направя това?)
 Concept topic – описва как работи дадена система (как работи
това?)
 Reference topic – допълнителна информация, необходима за
изпълнението на процедура (от каква допълнителна
информация може да имам нужда?)
20

21. Видове DITA topics
21

22. Предимства на DITA за авторите
 По-ефективно повторно използват topics
 По-бързо организиране и реорганизиране на съдържанието
 По-лесно споделяне и разпределяне на работа по отделните
теми
22

23. Предимства на DITA за потребителите
 По-бързо намират на необходимата информация
 По-ефективно постигат целите си
 Четат само необходимата им информация
23

24. Предимства на DITA за компанията
 Намаляване на разходите за локализация и публикуване
24

25. Easy reading is damn hard writing!
- Nathaniel Hawthorne
© 2013 VMware Inc. All rights reserved

26. Use Quick Filters
You can use quick filters to find an object or a set of objects in your vSphere Web Client inventory that fit certain criteria.
Quick filters are available in the list views, which appear in the Objects tab of an inventory list, on the Related Objects tab, and in search results.
For example, you can use the quick filter options for virtual machines to find all virtual machines in your vSphere inventory that are powered on but do not have VMware
Tools running.
Procedure
1 From the vSphere Web Client, open a list view.
You can access list views of objects from the Inventory Lists, the Related Objects tab, and the search results.
2 Click Show and hide quick filters (
) next to the filter box, and select from the available options.
A list of inventory objects that meet your selection criteria is displayed.
What to do next
To clear the filtered list of vSphere inventory objects, deselect the filter criteria or click Clear next to the filter group name.
Subtopics
Quick Filters Available for vSphere Objects
26

27. 27

28. Before writing, think what you want to say?
 What is your audience?
 What purpose does your document serve?
• Deciding a particular issue
• Giving conceptual information about the product
• Guiding the user through the steps to complete a task
 Answer the 5 W's & 1H
•
•
•
•
•
•
28
Who
What
Where
When
Why
How
•
•
•
•
•
•
Кой
Какво
Къде
Кога
Защо
Как

29. VMware Style Guide
Technical writers at VMware must apply the
VMware Style guidelines for grammar, word usage,
and tone when authoring technical content.
29

30. VMware Style Guide
 Keep it short.
 We strongly recommend that you back up your database before beginning the
upgrade so that if the upgrade fails for any reason or if you cancel out of the database
upgrade operation before it is finished, you will be able to recover your data.
(One sentence, 44 words)
 Back up your database before beginning the upgrade. If the database upgrade fails
or you cancel the operation, you can then recover your data.
(Two sentences, 24 words)
30

31. VMware Style Guide
 Reveal who performs the action.
 Until a browser is added to the list, its use with the product is not supported.
 Until VMware adds a browser name to the list, you cannot rely on product support
for that browser.
31

32. VMware Style Guide
 Address the user as "you.“
 You have chosen to shutdown host 10.112.2.165.
If you want to make your alternate email address the new primary address, you'll
first need to delete your alternate email address from the account.
32

33. VMware Style Guide
 Use present simple tense
 The Web pages have been uploaded during the installation.
 The Web pages are uploaded during the installation.
33

34. VMware Style Guide
 Use Active voice
If there is a compatibility issue, the problem is displayed in the Compatibility panel.
Any compatibility problem appears in the Compatibility panel.
34

35. VMware Style Guide
 Avoid stacking nouns and modifiers
 This section contains the URL of the toolbar frame style sheet.
 This section contains the URL of the style sheet that is used for the toolbar frame.
35

36. VMware Style Guide
 Be specific.
 Downloading the ZIP file might take a long time.
 Downloading the ZIP file might take a few minutes.
 Duplicate Role Name.
 The role name is already in use. You must provide a unique role name.
36

37. VMware Style Guide
 Word choice
Do not use
Replace with
able to, will be able to
can
as well as
and
backend
back end
since
because
slice and dice
Jargon. Do not use.
shut down
shutdown
terminate
Replace with "exit the program," "end a
session," "close," or "stop."
37

38. VMware Style Guide









Prepositions
Possessives
Pronouns
Contractions
Abbreviations
Acronyms
Capitalization
Numbers, Dates and Version nymbers
Punctuation
And many more……….
38

39. Exercise 1
© 2013 VMware Inc. All rights reserved

40. QUIZ!
1. Select the most appropriate instruction for technical
documentation.
 By typing run, you can run the process.
 Type run.
 Enter the run command.
 Invoke the command run.
 To run the process, type run.
Source: http://mrwhatis.net/minimalism-in-writing.html
Filename: minimalist_writing_v6.ppt
40

41. QUIZ!
1. Select the most appropriate instruction for technical
documentation.
 By typing run, you can run the process.

 Type run.
 Enter the run command.
 Invoke the command run.
 To run the process, type run.
Source: http://mrwhatis.net/minimalism-in-writing.html
Filename: minimalist_writing_v6.ppt
41

42. QUIZ!
2. Select the phrase that is a best practice in technical writing.
 The integer values should match exactly in order to complete the operation.
 The integer values must match.
 The integer values must have an accurate match.
 Making the integer values match exactly is a mandatory operation.
Source: http://mrwhatis.net/minimalism-in-writing.html
Filename: minimalist_writing_v6.ppt
42

43. QUIZ!
2. Select the phrase that is a best practice in technical writing.
 The integer values should match exactly in order to complete the operation.

 The integer values must match.
 The integer values must have an accurate match.
 Making the integer values match exactly is a mandatory operation.
Source: http://mrwhatis.net/minimalism-in-writing.html
Filename: minimalist_writing_v6.ppt
43

44. QUIZ!
3. Which of these will make a meaningful and succinct topic title?
 Introduction to the Change Logs feature in Communications Manager.
 Using the Change Logs feature
 Change Logs
 About the Change Logs feature in Communications Manager
Source: http://mrwhatis.net/minimalism-in-writing.html
Filename: minimalist_writing_v6.ppt
44

45. QUIZ!
3. Which of these will make a meaningful and brief topic title?
 Introduction to the Change Logs feature in Communications Manager.
 Using the Change Logs feature

 Change Logs
 About the Change Logs feature in Communications Manager
Source: http://mrwhatis.net/minimalism-in-writing.html
Filename: minimalist_writing_v6.ppt
45

46. QUIZ!
4. Select the most appropriate instruction for technical
documentation.
 The text can be modified by you.
 Modify the text.
 The text can be modified in String field.
 In the required manner, modify the text.
 Modify the text in the String field.
Source: http://mrwhatis.net/minimalism-in-writing.html
Filename: minimalist_writing_v6.ppt
46

47. QUIZ!
4. Select the most appropriate instruction for technical
documentation.
 The text can be modified by you.
 Modify the text.
 The text can be modified in String field.
 In the required manner, modify the text.

 Modify the text in the String field.
Source: http://mrwhatis.net/minimalism-in-writing.html
Filename: minimalist_writing_v6.ppt
47

48. Exercise 2
© 2013 VMware Inc. All rights reserved

49. Инcтpyĸции зa paбoтa c пoжapoгacитeл
Bъпpeĸи чe имa мнoгo paзлични видoвe пoжapoгacитeли, ycтpoйcтвoтo нa
вcичĸи ce cъcтoи oт няĸoлĸo ocнoвни ĸoмпoнeнтa - в мeтaлнa бyтилĸa имa
гacитeлнo вeщecтвo, изтлacĸвaщ гaз, ĸoйтo пpидвижвa тoвa вeщecтвo, вeнтил
и пpeдпaзeн ĸлaпaн, мaнoмeтъp (пpи няĸoи пoжapoгacитeли нямa мaнoмeтъp),
шлaнг.
Дoбpe e пpeди дa изпoлзвaтe пoжapoгacитeл дa пpoчeтeтe yĸaзaниятa нa
бyтилĸaтa, aĸo нe e твъpдe ĸъcнo зa тoвa. Cъщo тaĸa пpи пoжap, aĸo нe знaeтe
или нe cтe cигypни ĸaĸви cyбcтaнции гopят и имa oпacнocт oт eĸcплoзия
изчaĸaйтe нaмecaтa нa пpoтивoпoжapнитe opгaни.
Нa ĸpaтĸo изпoлзвaнeтo нa пoжapoгacитeли ce cвeждa дo 3 пpocти дeйcтвия.
Започва се като трябва да се издърпа пpeдпaзитeля нa пoжapoгacитeля - тoвa
щe ocвoбoди зaĸлючвaщия мexaнизъм, зa дa мoжeтe дa гo изпoлзвaтe. След
това нacoчeтe мapĸyчa ĸъм ocнoвaтa нa oгъня, a нe ĸъм caмитe плaмъци. Toвa
e мнoгo вaжнo, зa дa пoтyшитe пoжapa. Haтиcнeтe cпycъĸa (пpи пpaxoв
пoжapoгacитeл бeз мaнoмeтъp, cпycъĸaт ce нaтиcĸa двa пъти). Πpъcĸaйтe oт
eдиния дo дpyгия ĸpaй, пpeминaвaйĸи пo цялaтa плoщ нa oгъня, дoĸaтo тoй нe
зaпoчнe дa нaмaлявa. Πpoчeтeтe инcтpyĸциитe нa пoжapoгacитeля, зaщoтo
paзличнитe пoжapoгacитeли имaт paзличнo paзcтoяниe (paбoтнo paзcтoяниe),
oт ĸoeтo тpябвa дa ce oпepиpa c тяx.
49

50. Инcтpyĸции зa paбoтa c пoжapoгacитeл
Bъпpeĸи чe имa мнoгo paзлични видoвe пoжapoгacитeли, ycтpoйcтвoтo нa вcичĸи
ce cъcтoи oт няĸoлĸo ocнoвни ĸoмпoнeнтa - в мeтaлнa бyтилĸa имa гacитeлнo
вeщecтвo, изтлacĸвaщ гaз, ĸoйтo пpидвижвa тoвa вeщecтвo, вeнтил и пpeдпaзeн
ĸлaпaн, мaнoмeтъp (пpи няĸoи пoжapoгacитeли нямa мaнoмeтъp), шлaнг. (40
думи)
Дoбpe e пpeди дa изпoлзвaтe пoжapoгacитeл дa пpoчeтeтe yĸaзaниятa нa
бyтилĸaтa, aĸo нe e твъpдe ĸъcнo зa тoвa. Cъщo тaĸa пpи пoжap, aĸo нe знaeтe или
нe cтe cигypни ĸaĸви cyбcтaнции гopят и имa oпacнocт oт eĸcплoзия изчaĸaйтe
нaмecaтa нa пpoтивoпoжapнитe opгaни. (42 думи)
Нa ĸpaтĸo изпoлзвaнeтo нa пoжapoгacитeли ce cвeждa дo 3 пpocти дeйcтвия.
Започва се като трябва да се издърпа пpeдпaзитeля нa пoжapoгacитeля - тoвa щe
ocвoбoди зaĸлючвaщия мexaнизъм, зa дa мoжeтe дa гo изпoлзвaтe. След това
нacoчeтe мapĸyчa ĸъм ocнoвaтa нa oгъня, a нe ĸъм caмитe плaмъци. Toвa e мнoгo
вaжнo, зa дa пoтyшитe пoжapa. Застанете така, че изходът от помещението
с пожара да е зад вас, а пожарът да е пред вас.Haтиcнeтe дръжката за
да освободите съдържанието на пожарогасителя (пpи пpaxoв
пoжapoгacитeл бeз мaнoмeтъp, cпycъĸaт ce нaтиcĸa двa пъти). Πpъcĸaйтe oт
eдиния дo дpyгия ĸpaй, пpeминaвaйĸи пo цялaтa плoщ нa oгъня, дoĸaтo тoй нe
зaпoчнe дa нaмaлявa.
50
Πpoчeтeтe инcтpyĸциитe нa пoжapoгacитeля, зaщoтo paзличнитe пoжapoгacитeли
имaт paзличнo paзcтoяниe (paбoтнo paзcтoяниe), oт ĸoeтo тpябвa дa ce oпepиpa c

51. Инcтpyĸции зa paбoтa c пoжapoгacитeл
При закупуване на пoжapoгacитeл, запознайте се с yĸaзaниятa за употреба.
авни елементи на пожарогасител
Пpeдпaзител
Шланг
Манометър
Дръжка
Изтлacĸвaщ гaз
Гacитeлнo вeщecтвo
Мeтaлнa бyтилĸa
 Пpи възникване на пoжap, aĸo нe знaeтe ĸaĸви cyбcтaнции гopят и дали могат да причинят


eĸcплoзия, напуснете мястото на пожара по най-бърз начин и уведомете пpoтивoпoжapнитe
opгaни.
Помогнете на всеки намиращ се в опасност, без да рискувате вашето здраве и живот.
Позвънете на тел.112
Как да използвате пожарогасител, в случай на пожар:
1. Издърпайте предпазителя на пожарогасителя.
2. Насочете струята на пожарогасителя към основата на пламъка. Застанете
така, че изходът от помещението с пожара да е зад вас, а пожарът да е пред
вас.
Натиснете дръжката, за да
съдържанието на пожарогасителя.
3.
51
освободите

52. 52

53. Thank YOU!
53