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