Writing for dartlang.org

The Dart site at www.dartlang.org (and in particular, www.dartlang.org/articles/) is open to contributions. The site uses Markdown (or HTML, if necessary) with some special additions. The best way to contribute depends on the scope of your changes:

• For small fixes like typos, you can make your edits right here in github by navigating to the file and clicking Edit.
• For larger fixes, it’s great if you can contribute using git, chromiumcodereview, and our site format, but we can be flexible.
• If you're writing a new article, we recommend doing the initial writing and technical reviews in a Google Drive document. Once your article is vetted, you (or we) can convert it to Markdown and publish it.

For details on how to format your content, see Formatting Tips.

Note: We also love contributions to the API docs (api.dartlang.org), which are generated from source code and doc comments. For details, see Writing API Documentation.

Contents

• Before you write
  • Sign our CLA
  • File a bug (optional)
• Write the article
  • Initial draft and reviews
  • Conventions
  • Choosing a path
• Write code samples
• Write an author page

Yet to add: Content on creating a CL, getting it reviewed, and getting the article published and advertised.

Before you write

Sign our CLA

Sign Google's contributor license agreement before you send us any contributions. (If you're a Google employee, you can skip this step.)

File a bug (optional)

If you file a bug, we'll be able to plan our work better, and you'll be able to avoid wasting your time on duplicate work. Typo fixes don't require filing a bug; new articles do. Use your judgment for everything in between.

Write the article

Initial draft and reviews

Some authors like to create the article in a Google Drive document, moving to Markdown once the majority of comments have been dealt with.

Follow conventions

We prefer a 1 or 2-paragraph intro, followed by a TOC, followed by content. [Point to example]

Keep code copyable. Avoid giving bad examples, whenever possible. If you need to give bad examples, make it impossible to mistake them for good ones. (See the Dart Style Guide for a nice scheme.)

Make sure that API doc links don't have the version embedded (unless you really want that). For example, don't link to https://api.dartlang.org/1.12.2/dart-core/Object-class.html. Instead, change the version string to either stable or dev:

• https://api.dartlang.org/stable/dart-core/Object-class.html
• https://api.dartlang.org/dev/dart-core/Object-class.html

Choose a path

Each article (or group of articles on a single subject) goes into its own subdirectory of src/site/articles. For SEO reasons, try to put good buzzwords in the path, and separate words with dashes (-), not underscores.

Some examples:

• doc-comment-guidelines
• idiomatic-dart
• improving-the-dom
• m1-language-changes
• reflection-with-mirrors
• snapshots
• style-guide

To get the top matter and styles right, copy a file such as src/site/snapshots/index.markdown.

Write code samples

Create a code/ directory inside your article’s directory, and put .dart files there that contain the code from your article. We’ll continuously run dart_analyzer (at least) on the articles’ code, so we’ll know as soon as the code breaks.

Write an author page

If you don’t yet have an author page, create one and add a link to it from /authors/index.html. Author pages can help Google provide pretty search results for your articles.

Here's how to create your author page:

1. Go to src/site/authors.
2. Copy seth-ladd.html to your-name.html.
3. Modify the info, removing the twitter and me: links if you don’t have (or don’t want to expose your) twitter or external G+ accounts.
4. Edit index.html to add your name (alphabetically by first name).