Skip to content

Latest commit

 

History

History
131 lines (79 loc) · 6.32 KB

CONTRIBUTING.md

File metadata and controls

131 lines (79 loc) · 6.32 KB

Contributing to the TinyMCE developer documentation

This page outlines how you can provide feedback and contribute to TinyMCE documentation.

Contributor Code of Conduct

For our Contributor Code of Conduct, visit our Contributor Covenant Code of Conduct on GitHub.

How to contribute to TinyMCE's documentation

We welcome people with technical writing experience to help make TinyMCE's docs as useful to our community as possible. Although you don't need to be an expert developer to contribute, a basic understanding of software development is helpful.

What is more important is your ability to articulate complex ideas. Our goal is to help developers understand TinyMCE's functionality as quickly as possible.

Simply branch the docs GitHub repository and submit a PR, or reach out to the TinyMCE docs team if you have a specific question.

TinyMCE documentation tech stack

The documentation is built with Jekyll. Text files are written in kramdown and published on GitHub. You will find the repo here.

Markdown & code syntax

The documentation is written in kramdown Flavored Markdown. If you are not familiar with kramdown read this.

Highlighting

Code language syntax and associated elements are highlighted using an open and closing backtick. For example, this object is actually enclosed with backticks like this: `object`.

Highlight words relating specifically to executable parts of software languages. Keys and their values when pertaining to objects and methods (particularly the case with TinyMCE) should have backticks. We cannot cover every use case here and contributors need to use their best judgment. What is more important is your ability to articulate complex ideas.

Code snippets

Code snippets should always be complete, executable code blocks starting with the tinymce object. We write code snippets by enclosing the example code within three opening and closing backticks. The first set of backticks is immediately followed by the code's language, which helps correct syntax highlighting: typically, html, css, js (and sometimes php).

Include any key values pairs and method options that are required to enable a user to test the snippet in a local HTML file. You do not need to include the html surrounding the tinymce object that would be required to make the snippet work.

For example, this is good:

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'codesample',
  toolbar: 'codesample'
});

This is not:

tinymce.init({
  ...
  plugins: 'codesample',
  toolbar: 'codesample'
  ...
});

URLs and links

Resources to be linked take the form of placing the linked text between brackets and the URL between parenthesis. Linking an external resource looks like this:

hello, [text to link](http://www.example.com) to the URL example.com.

Codepens

Codepens can be added to content using the "codepen.html" include, such as:

{% include codepen.html id="basic-example" %}

There are several options for this include file - please see _includes/codepen.html for details.

The source for each CodePen is store in the _includes/codepens/ directory.

Adding metadata to a page

Every page should have a meta section starting at line 1 containing information that is both informative and system critical. If you are creating a page or editing one that currently has inadequate meta information, please read the comments next to the default meta fields below.

---                // Three dashes at the start and end of the meta section, must be included.
layout: default    // In most cases leave this as 'default'.
title:             // The nav.yml references this so it must be included and it should be brief.
title_nav:         // Descriptive title for the navigation bar, if omitted nav defaults to title field.
description_short: // Short description for the grid layouts.
description:       // Detailed description at page level for the header section under the title.
keywords:          // Space-separated list of keywords in the content.
---

Style Guide

TinyMCE v. tinymce

Use the capitalized version of TinyMCE when referring to the open source project or the editor. Use lowercase when referring to the tinymce JavaScript object.

Title capitalization

For titles use "Sentence case capitalization". Sentence case capitalization is more comfortable to read in technical documentation.

Spelling

Use United States English. For example, behavior rather than behaviour, and canceled rather than cancelled.

Proper names

When referring to the name of a development language we use the proper name or, where appropriate, the industry convention. For example, HTML, CSS, JavaScript, jQuery, React, AngularJS (not HTML, css, Jquery or React-js.)

The exception to this rule is when we are talking about the code itself (see the note above about TinyMCE v. tinymce). For example, write "HTML is great" when talking about the HTML language, but write, "escape your html" when talking about action with or within a codebase.

Active voice v. Passive voice

Use active voice. Passive voice decreases readability and comprehension.

Adverbs

Avoid adverbs, such as: very or usually.

Pronouns

Avoid pronouns, such as: we, you, or I.

First, Second, or Third Person Perspective

Write in a third person perspective, such as: He, she, they, or them.

Keep it simple

Use short, simple words where possible. Use formal language, do not use: slang, acronyms, initialisms, abbreviations, and ambiguous contractions (such as there'd, or it'll).