View
183
Download
4
Category
Preview:
DESCRIPTION
Стил и стандарти в техническото писане. Тази презентация ще ви запознае с основните стандарти за писане на техническа документация в софтуерния бранш. Защо изобщо ни трябват стандарти и какво налага прилагането на стилови правила?
Citation preview
© 2013 VMware Inc. All rights reserved
Стил и стандарти
Ко? Не! … ама по-добре ДАБранимира Димитрова
Йордан Георгиев
Ралица Цонева
2
Инструкция за експлоатация
Как се предава информацията?
W*F is standard?
Защо са ни стандарти и какво е Style guide?
Основни изисквания към документацията
Какво е минимализъм и topic based writing?
Какво е DITA като стандарт?
Примери за правила и как ги прилагаме
3
Как се предава информацията?
Ами зависи...
Всяка индустрия има правила
Кой е потребителят?
Какво искаме да му кажем?
Колко ще инвестираме?
4
Текст
5
Графика
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 за компанията
Намаляване на разходите за локализация и публикуване
© 2013 VMware Inc. All rights reserved
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……….
© 2013 VMware Inc. All rights reserved
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
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
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!
Source: http://mrwhatis.net/minimalism-in-writing.html Filename: minimalist_writing_v6.ppt
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!
Source: http://mrwhatis.net/minimalism-in-writing.html Filename: minimalist_writing_v6.ppt
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!
Source: http://mrwhatis.net/minimalism-in-writing.html Filename: minimalist_writing_v6.ppt
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!
Source: http://mrwhatis.net/minimalism-in-writing.html Filename: minimalist_writing_v6.ppt
46
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.
QUIZ!
Source: http://mrwhatis.net/minimalism-in-writing.html Filename: minimalist_writing_v6.ppt
47
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.
QUIZ!
Source: http://mrwhatis.net/minimalism-in-writing.html Filename: minimalist_writing_v6.ppt
© 2013 VMware Inc. All rights reserved
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!
Recommended