View
220
Download
0
Tags:
Embed Size (px)
Citation preview
Process and Writing Styles
Tina StanchevaDoroteya Agayna
Telerik Software Academyacademy.telerik.com
http://academy.telerik.com
Writing Documentation
Table of Contents Documentation Tools Basic Process Writing Content
Getting Started
Good Practices
Use Sections
Use Bulleted Lists and Tables
Visualize the information
Logically structure the information
2
Documentation Tools
GitHub Jekyll A Markdown Editor
MarkdownPad – a stand-alone editor
Writage – a plug-in for MS Word
Basic Process (1/3) Take the story-outcome document of the new feature from the developer(s).
Get hands-on experience with the new feature.
Identify the related features and the articles that need updating.
Identify the newly supported scenario and define the new articles.
Decide where to place the new articles in the existing structure of the documentation.
Basic Process (2/3) Choose a basic scenario for each new article.
Prepare a working sample application that exercises the new feature.
Prepare the screenshots that demonstrate the implementation process.
Prepare hyperlinks to other relevant documentation articles.
Research if there are generic limitations related to the feature.
Basic Process (3/3) Write the content of the article using the previously gathered information.
Test yourself – try reproducing the sample application following the guidance of your articles.
Review the article with the appropriate team members.
Writing Content (1/7) Getting Started
Choose a title Describing the content
Describing the purpose of the tutorial
Use as few words as possible
Write an introduction A few sentences to summarize
Telerik RadTreeView provides check boxes/radio buttons displayed next to each item. The RadTreeView allows the user to check/uncheck the nodes and to perform various tasks. with the collection of checked nodes.
Writing Content (2/7)
Good Practices Write clearly
Short informative sentences in active voice.
Use consistent terminology, tone, and style
Avoid mixing different tones (friendly or less so)
Structure each content page Clear, well-located headings
Short readable paragraphs.
Writing Content (3/7) Use Sections
Group related information and functions Wrap them in sections
Headers should summarize text below
To make text easy for scanning
Example:
Using RadEditor in ASP.NET MVCGetting the content of RadEditorSetting the content of RadEditor
Writing Content (4/7) Use Bulleted Lists
Consider using bulleted lists to describe the properties and events of a control.
The following properties are related to the minimize feature:
• IsMinimizable - use this property to enable/disable the minimization functionality of the RibbonView. The default value is True.
• IsMinimized - use this property to set or get the current minimize state of the RibbonView.
• IsMinimizedPopupOpen - use this property to get whether the minimized popup menu of the RibbonView is opened or not.
10
Writing Content (5/7) Use Tables
Consider using tables to describe the properties and events of a control:
11
Writing Content (6/7) Visualize the Information
Use images, graphs, charts where they might convey complex information more quickly:
12
Writing Content (7/7) Logically structure the information
List sample, logically ordered steps for the readers to follow:
In order to create a custom mask token, you need to define a new class that should implement the ITokenValidationRule interface. …Then you can start configuring the custom token through the following properties:…When you define the properties that describe the custom token, you need to implement a logic that controls whether the entered character is valid for that custom token…Finally the custom token will have the following definition:
13
Recommendations
14
Use a friendly tone
If you need to perform additional actions on uploaded files before saving them (for example, if you are using custom fields), or if you want to manipulate them in memory without saving them,
15
you can use the RadUpload server-side API. You can use the server-side API to rename uploaded files or save them into a database, or other storage medium.
Ask questions and provide answers
"I need each bar in a bar chart to be a different color. How do I do this?“
- By default RadChart is designed so that all bars from a series have the same colors. If you need each to have a different color, loop through each chart series item and assign them a color from an array. This should be done after binding the chart, so the chart series items are available.
16
Describe the information with a code
snippet
17
Use note-like sections Use note-like sections within the topics to draw attention to important information
18
форум програмиране, форум уеб дизайнкурсове и уроци по програмиране, уеб дизайн – безплатно
програмиране за деца – безплатни курсове и уроцибезплатен SEO курс - оптимизация за търсачки
уроци по уеб дизайн, HTML, CSS, JavaScript, Photoshop
уроци по програмиране и уеб дизайн за ученициASP.NET MVC курс – HTML, SQL, C#, .NET, ASP.NET MVC
безплатен курс "Разработка на софтуер в cloud среда"
BG Coder - онлайн състезателна система - online judge
курсове и уроци по програмиране, книги – безплатно от Наков
безплатен курс "Качествен програмен код"
алго академия – състезателно програмиране, състезания
ASP.NET курс - уеб програмиране, бази данни, C#, .NET, ASP.NETкурсове и уроци по програмиране – Телерик академия
курс мобилни приложения с iPhone, Android, WP7, PhoneGap
free C# book, безплатна книга C#, книга Java, книга C#Дончо Минков - сайт за програмиранеНиколай Костов - блог за програмиранеC# курс, програмиране, безплатно
?
? ? ??
?? ?
?
?
?
??
?
?
? ?
Questions?
?
Documentation Writing Style
http://academy.telerik.com