Skip to content

Commit 6e6fa4b

Browse files
author
Ramesh Kannan
committed
Added ReadMe & Style Guide
1 parent 332618e commit 6e6fa4b

File tree

2 files changed

+281
-0
lines changed

2 files changed

+281
-0
lines changed

‎readme.md

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# Documentation Guidelines
2+
3+
This section contains guidelines on naming files, sections, documents and other document elements.
4+
5+
> **NOTE**: Some of the items are marked as TODO which will be documented later.
6+
7+
## File naming Convention:
8+
* All files should have `.md` extension.
9+
* Separate words in file names should be hyphenated
10+
* File names of the documents should have one or two-word names that describe the material covered in the document.
11+
* The full title of the document should be in the file name.
12+
* Phrase title and description in a way that users can determine what questions the text will answer, and material that will be addressed, without reading the content. This eases the time spent looking for answers, and improvises search/scanning, and possibly **SEO**.
13+
* Provide titles and headers in the form of “Using foo” over “How to Foo.”
14+
15+
> For example, at the top section of each MD file,
16+
17+
> **Title :** Getting started with Chart widget for Syncfusion Essential JS
18+
19+
> **Description :** How to create a chart, add series, enable tooltip and other functionalities.
20+
21+
22+
## Markdown Syntax Guideline
23+
* Follow the syntax mentioned in this [link](http://kramdown.gettalong.org/syntax.html) for most of the elements. There are some elements which need special styling or additional settings to do. Those have been described in the below topics.
24+
25+
## General
26+
* Do not bold the words unnecessarily.
27+
* Use [inline code style](http://kramdown.gettalong.org/quickref.html#inline-code) wherever it is possible to highlight the keywords, variables or one line code examples that come within the paragraph.
28+
29+
### Cross-reference
30+
* Link within the page (if you have a title with space, use hyphen (-))
31+
32+
> **Syntax**: \[Link name](#title-name)
33+
34+
> **Example**: \[How to best read this user guide] (#how-to-best-read-this-user-guide)
35+
36+
* Link to the other page within the same platform documentation (using relative path). Tooltip text is optional.
37+
38+
> **Syntax**: \[Link name](relative path "Tooltip text")
39+
40+
> **Example**: \[Barcode](/js/Barcode/Getting-Started "Barcode Getting Started")
41+
42+
### Table
43+
* Use the [kramdown syntax](http://kramdown.gettalong.org/syntax.html#tables) for creating the tables.
44+
* **Advanced tables**: If you want to create an advanced tables with row span or column span or with code snippets, you can go with the standard html table syntax as described below.
45+
46+
> 1. start with `<table>` tag. Tag should be left indented and should have empty space in left side.
47+
48+
> 2. Provide `TH` tag for table headers.
49+
50+
> 3. Code snippet can include within `<td> [code snippet] </td>`. Follow the same pattern like code snippet.
51+
52+
* Do not provide table captions.
53+
* You should use the below markdown syntax if you want to use markdown syntax within the html tags.
54+
55+
> \{{'<MarkdownSyntax>' | markdownify }}
56+
57+
> **Example**:
58+
59+
> \{{'\[syncfusion](http://cdn.syncfusion.com/js/assets/external/jquery-1.10.2.min.js)'| markdownify }}
60+
61+
62+
63+
### Image
64+
65+
* Make sure image is not resized or blurred.
66+
* Caption is not necessary to provide for all images except for the case where we will have displayed more than one image.
67+
68+
* Adding Image : General markdown [syntax](http://kramdown.gettalong.org/syntax.html#images) will work.
69+
70+
> **Syntax**: \!\[Alt text](imagepath)
71+
72+
> **Example**: \!\[Alt text](/path/to/img.jpg)
73+
74+
* Adding image with caption:
75+
76+
> **Syntax**: \{% include image.html url="image path" caption="caption text"%}
77+
78+
> **Example**: \{% include image.html url="/js/DatePicker/Appearance-and-Styling_images/Appearance-and-Styling_img2.png" caption="caption text"%}
79+
80+
* Maximum width of the image should be 750 PX
81+
* Maximum height of the image should be 550 PX
82+
* Image format should be either .jpeg or .png format
83+
* Size of the image should not exceed 20 to 40 KB
84+
* If you are including the image to show an output of a code block, make sure the exact output can see the user also when he executes the same code snippet.
85+
86+
### Code Blocks
87+
* Refer [this page](http://haisum.github.io/2014/11/07/jekyll-pygments-supported-highlighters/) for Code block syntax and supported languages.
88+
* Align the code snippets using following free formatters:
89+
[JS](http://jsbeautifier.org/) ,
90+
[HTML](http://www.freeformatter.com/html-formatter.html)
91+
* Remove extra lines added within the code block.
92+
* Make sure the given code block runs without any issues.
93+
* JSRender template syntax can be rendered by the following syntax :
94+
95+
> \{{"{{"}} code block here {{}}}}
96+
97+
98+
### Bullet style
99+
* Refer the syntax provided in the [Kramdown site](http://kramdown.gettalong.org/syntax.html#lists).
100+
* Do not provide a line gap between the bullet points.
101+
102+
### Notes style
103+
104+
* To add the different type of predefined blockqoute use the below syntax. Since we will insert the title or relevant icon for this block of content, do not add the **"Title"**.
105+
106+
**Information** or **Notes**
107+
> **Syntax**: I> [Content]
108+
109+
> **Example**: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis volutpat, elit eget iaculis venenatis
110+
111+
**Warning**
112+
> **Syntax**: W> [Content]
113+
114+
> **Example**: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis volutpat, elit eget iaculis venenatis
115+
116+
**Errors**
117+
> **Syntax**: E> [Content]
118+
119+
> **Example**: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis volutpat, elit eget iaculis venenatis
120+
121+
**Tips**
122+
> **Syntax**: T> [Content]
123+
124+
> **Example**: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis volutpat, elit eget iaculis venenatis
125+
126+
### Notes multiple paragraph style
127+
* Use the BR tag between the content to enable multiple paragraph style.
128+
129+
130+
**Tips**
131+
> **Syntax**: T> [Content]
132+
133+
> **Example**: Lorem ipsum dolor sit amet, consectetur adipiscing elit. **<BR>**Duis volutpat, elit eget iaculis venenatis
134+
135+
136+
137+
### See also
138+
139+
* See also section can be added at the bottom of the page using the below syntax
140+
141+
> **Syntax**:
142+
> {% seealso %}
143+
> [Content]
144+
> {% endseealso %}
145+
146+
147+
> **Example**:
148+
> {% seealso %}
149+
> [See the Cross Reference section](#Cross-reference)
150+
> {% endseealso %}
151+
152+
153+
### JS Playground integration
154+
* Todo -> How to link the JS Playground link on top of the each code blocks?
155+
156+
### Keyboard shortcuts
157+
* Enclose the each keys with `<kbd>` tag to display the keys with different styling. For ex, <kbd>Ctrl</kbd>+<kbd>A</kbd> .
158+
159+
### Product Release Version variable
160+
* To add the version number in the documentation, use the below variables that replace the corresponding release version number while publishing. So that, always your content will contains the latest release version number.
161+
162+
| Variable Name | Output | Description |
163+
| ---------------------------------|:--------------:|:----------------------------------------------------------------------:|
164+
| {{ site.releaseversion }} | 13.2.0.29 |Syncfusion Essential Studio version |
165+
| {{ site.20esreleaseversion }} | 13.1200.0.29 |Syncfusion Essential Studio assemblies version for .NET Framework 2.0 |
166+
| {{ site.35esreleaseversion }} | 13.1350.0.29 |Syncfusion Essential Studio assemblies version for .NET Framework 3.5 |
167+
| {{ site.40esreleaseversion }} | 13.1400.0.29 |Syncfusion Essential Studio assemblies version for .NET Framework 4.0 |
168+
| {{ site.45esreleaseversion }} | 13.1450.0.29 |Syncfusion Essential Studio assemblies version for .NET Framework 4.5 |
169+
| {{ site.451esreleaseversion }} | 13.1451.0.29 |Syncfusion Essential Studio assemblies version for .NET Framework 4.5.1 |
170+
| {{ site.mvc3releaseversion }} | 13.1300.0.29 |Syncfusion Essential Studio assemblies based on MVC Version 3.0 |
171+
| {{ site.mvc4releaseversion }} | 13.1400.0.29 |Syncfusion Essential Studio assemblies based on MVC Version 4.0 |
172+
| {{ site.mvc5releaseversion }} | 13.1500.0.29 |Syncfusion Essential Studio assemblies based on MVC Version 5.0 |
173+
174+
## API Reference Guideline
175+
176+
### Naming Standards
177+
* Use the JS API naming standards mentioned in the following page - [API Naming Standards](https://syncfusion.atlassian.net/wiki/display/JS/API+Naming+Standards)
178+
179+
# See Also
180+
[Style Guide](/style-guide.md)

‎style-guide.md

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
## Style Guide
2+
3+
### General guidelines
4+
* Remember that no documentation is better than poor quality documentation.
5+
* Also, remember that "Less is more" when it comes to technical documentation.
6+
* Imagine that every word takes up unnecessary space so constantly look for words that can be removed. Please note that this is different from not writing anything at all. We still need to convey the maximum possible information using the minimum possible words.
7+
* Do not repeat content from other sections of documentation. Each section should serve a purpose and don’t let it overlap.
8+
* For example, don’t talk about all the possible parameters that a method can take, just point to the class reference.
9+
* Avoid any form of marketing content.
10+
* Do not explain code.
11+
* For example, here we are instantiating the chart using the overload that takes a string and a number, then we..
12+
* Code samples should be accompanied by text that provides additional insights.
13+
* For example, DateTime axis has been used here but the chart also has built-in support for handling several other data types (link to other sections of user guide or API reference)
14+
* Write content from an user perspective and not from the developer or product perspective.
15+
* Constantly check the flow of the document as you write it. Users shouldn’t feel lost.
16+
* Write documentation keeping the target audience in mind. In our case, we need to fix a specific level of technical user.
17+
* For example, we have to assume that the user would know how to create a project in Visual Studio and add reference to the required assemblies
18+
19+
20+
### Referencing
21+
22+
* For API references (i.e. functions, operators, methods, settings) always reference only the **first occurrence** of the reference in a section. You should always reference objects, except in section headings.
23+
* Structure references with the why first; the link second.
24+
25+
_For example, instead of this:_
26+
27+
refer the same steps mentioned here in the [manual method](/js/control-initialization#adding-syncfusion-widget-into-your-html-page) to add the Syncfusion datepicker widget into the HTML page.
28+
29+
_Type this:_
30+
to add the Syncfusion datepicker widget into the HTML page, refer the same steps mentioned here in the [manual method](/js/control-initialization#adding-syncfusion-widget-into-your-html-page).
31+
32+
33+
### Things to avoid
34+
* Remove all out of date content
35+
* Ensure that there are no missing steps in a tutorial. Also, ensure that all code in tutorials are working.
36+
* Avoid having large amounts of text without accompanying code
37+
* Incomplete API documentation makes the product look immature.
38+
39+
### General English guidelines
40+
* Use the second person instead of first person
41+
* We will now see how to create a line chart - Incorrect
42+
* _You can create a line chart as shown below_ - Correct
43+
* Do not use a period after every item in a list
44+
* Write units in words
45+
* _50 megabytes_ - Correct
46+
* 50 MB - Incorrect
47+
* Each paragraph should only talk about one topic. Each sentence should only talk about one idea.
48+
* Each sentence should have less than 25 words.
49+
* Write in a neutral tone without marketing content
50+
* Essential chart has built in support for over 10 powerful technical indicators - Incorrect
51+
* _Essential chart has built in support for over 10 technical indicators_ - Correct
52+
* Constantly review the document that you are writing to see if any words can be removed without changing the information conveyed.
53+
* You can use a colon after the words "following" or "follows."
54+
* Use [American English](https://syncfusion.atlassian.net/wiki/display/SYNC/American+and+British+English+spelling+differences) and date formats.
55+
* Behavior vs Behaviour
56+
* Prefer **present tense** always except in some special criteria to use other tenses.
57+
* You will have to send the corrupted word document for troubleshooting. - Incorrect
58+
* _Please send the corrupted word document for troubleshooting._ - Correct
59+
* Avoid using gender specific words like she, he, him or her.
60+
* When you first use an acronym in a document, you should write out the full term and enclose the acronym in parentheses immediately after the term
61+
* This guide shows you how to configure the chart control within your favorite Integrated Development Environment (IDE)
62+
* Use oxford comma when referring to a list of three or more items
63+
* The data visualization suite consists of Chart, Gauge, and Map.
64+
* Always refer to the control name with proper casing
65+
* SfDataGrid vs Datagrid or Data Grid etc.
66+
* Make sure you do not confuse with these [tricky words](https://syncfusion.atlassian.net/wiki/display/SYNC/Similar+sounding+words+-+Homophones).
67+
* Always spell check using a tool like Microsoft Word.
68+
69+
### Structure of good documentation
70+
* Getting started tutorials
71+
* Write from a real world usage perspective
72+
* For example, customers would use DocIO for one of the following purposes
73+
* Dynamically generate reports based on templates.
74+
1. Load Template
75+
2. Mail merge
76+
3. Save as Doc or PDF
77+
* Document structure manipulation
78+
1. Load document
79+
2. Find a specific table
80+
3. Read its contents
81+
4. Replace with another table
82+
5. Save changes
83+
* Creating documents from code
84+
* Is there a reason why we need this in documentation since no end user would create the document from scratch instead of using a template since that option is a lot easier.
85+
* This can be documented as a side note under the "Dynamic document generation" section.
86+
* Converting from one file format to another (DOC To PDF)
87+
* Document best practices. For example, do we create an invoice from scratch or is it recommended to start from a template?
88+
* Document the most common issues encountered.
89+
* Link to demos where necessary.
90+
* Let users edit sample code in playground.
91+
* Possible workflow
92+
1. Create document outline
93+
2. Document first purely using bullet points
94+
3. Form sentences using language guidelines.
95+
96+
97+
### External references
98+
* <http://www.bartleby.com/141/>
99+
* <https://wiki.ubuntu.com/DocumentationTeam/StyleGuide/SpellingPunctuationGrammar>
100+
* <http://wiki.openbravo.com/wiki/Documentation_Style_Guide#Use_US_English>
101+
* <http://docs.basho.com/riak/latest/community/style-guide/>

0 commit comments

Comments
 (0)