Style and Standards in Technical Communications

© 2013 VMware Inc. All rights reserved

Стил и стандарти

Ко? Не! … ама по-добре ДАБранимира Димитрова

Йордан Георгиев

Ралица Цонева

2

Инструкция за експлоатация

Как се предава информацията?

W*F is standard?

Защо са ни стандарти и какво е Style guide?

Основни изисквания към документацията

Какво е минимализъм и topic based writing?

Какво е DITA като стандарт?

Примери за правила и как ги прилагаме

3

Как се предава информацията?

Ами зависи...

Всяка индустрия има правила

Кой е потребителят?

Какво искаме да му кажем?

Колко ще инвестираме?

4

Текст

5

Графика

6

Видео

VMware Technical Publications Video Channel

http://www.youtube.com/user/VMwareTechPubs

7

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

8

9

Опит за дефиниция

Стандартите са документи, разработени с консенсус на основата на обединяване на резултатите от науката, технологиите и производствения опит.

Стандартите са общопризнати правила и норми и може да включват подробни технически спецификации (характеристики и изисквания към продуктите), процедури за производство, методи за изпитване и оценяване на съответствието.

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

Стандартите се разработват, преработват, изменят, коригират или отменят в зависимост от новостите в развитието на науката и технологиите. За да може да се отговори на потребностите на обществото и пазара, непрекъснато расте необходимостта от разработване на стандарти.

Стандартите са пряко свързани както с начина ни на живот, така и с условията на работа, като все по-често обхващат и услугите. Много често, дори когато не го осъзнаваме, стандартите правят живота ни по-безопасен, по-здравословен и по-лесен. Те са средство за информация, улесняват търговията и общуването между партньорите.

Стандартите подпомагат икономическото развитие, което е в полза на цялото общество.Последните изследвания показват, че с разработване, приемане и прилагане на стандартите в развитите европейски страни се спестяват около 15 милиарда евро за година за изследване и разработване на нови технологии за производство.

/Български институт по стандартизация/

Общоприети правила, които се следват от всички с цел уеднаквяване на крайния продукт и повишаване на качеството.

10

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

Andrew Tanenbaum

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

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.

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.

14

Какво е Style Guide

100 = 1 ???

15

Що, бе, Миме?

Потребителят знае какво да очаква

Има представа къде да търси съответната информация

Не се налага да „разгадава“ стиловете

Не се налага да чете излишна информация

Безпроблемно ползване на продукта=CA$H

16

Хубаво, ама много зор, бе!

Изисква се време за създаването

Изисква се време за осъвременяването на стандарта

Хората трябва да се обучават непрекъснато

Творчеството не е на почит?

17

Какво е минимализъм в техническата документация?

Предоставяне само на необходимото

Премахване на несъществената информация

Фокус върху осъществяване на целите на потребителя, а не върху възможностите на продукта

Подпомагане на потребителя за извършването на задача или решаването на проблем

Предоставяне на необходимата информация на правилното място

18

Topic-based writing

Тopic – самостоятелна единица информация

Темата има заглавие и съдържание

Една тема съдържа една самостоятелна процедура, концепция или справочна информация

19

DITA като стандарт за topic-based writing

DITA – Darwin Information Typing Architecture

DITA се основава на принципите на минимализма и тематичното писане

DITA изпозлва семантични XML елементи

20

Видове DITA topics

Task topic – описва една процедура (как да направя това?)

Concept topic – описва как работи дадена система (как работи това?)

Reference topic – допълнителна информация, необходима за изпълнението на процедура (от каква допълнителна информация може да имам нужда?)

21

Видове DITA topics

22

Предимства на DITA за авторите

По-ефективно повторно използват topics

По-бързо организиране и реорганизиране на съдържанието

По-лесно споделяне и разпределяне на работа по отделните теми

23

Предимства на DITA за потребителите

По-бързо намират на необходимата информация

По-ефективно постигат целите си

Четат само необходимата им информация

24

Предимства на DITA за компанията

Намаляване на разходите за локализация и публикуване


Easy reading is damn hard writing!

- Nathaniel Hawthorne

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

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

• Кой• Какво• Къде• Кога• Защо• Как

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

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)

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.

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.

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.

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.

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.

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.

37

VMware Style Guide

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

Word choice

38

VMware Style Guide

Prepositions

Possessives

Pronouns

Contractions

Abbreviations

Acronyms

Capitalization

Numbers, Dates and Version nymbers

Punctuation

And many more……….


Exercise 1

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

http://mrwhatis.net/minimalism-in-writing.html





41

QUIZ!


By typing run, you can run the process.

Type run.

Enter the run command.

Invoke the command run.

To run the process, type run.







42

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.

QUIZ!







43

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.

QUIZ!







44

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

QUIZ!







45

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

QUIZ!







46


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.

QUIZ!







47


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.

QUIZ!








Exercise 2

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.

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.

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

51

Как да използвате пожарогасител, в случай на пожар: 1. Издърпайте предпазителя на пожарогасителя.

До идването на противопожарните органи, останете на мястото на пожара и наблюдавайте да не се възстанови огъня. В случай на възобновяване на огъня, повторете стъпките по гасене с пожарогасителя. При изчерпване на активното вещество в пожарогасителя, напуснете мястото на пожара по най-бърз начин.

Инcтpyĸции зa paбoтa c пoжapoгacитeл

Съставни елементи на пожарогасител

Мeтaлнa бyтилĸa

Гacитeлнo вeщecтвo

Изтлacĸвaщ гaз

Пpeдп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

При закупуване на пoжapoгacитeл, запознайте се с yĸaзaниятa за употреба.

2. Насочете струята на пожарогасителя към основата на пламъка. Застанете така, че изходът от помещението с пожара да е зад вас, а пожарът да е пред вас.

3. Натиснете дръжката, за да освободите съдържанието на пожарогасителя.

52

53

Thank YOU!

Education

Style and Standards in Technical Communications