-
Notifications
You must be signed in to change notification settings - Fork 149
Writing for dartlang.org
(This page isn't done yet, but it's probably more useful than having nothing at all.)
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. It’s great if you can contribute using git, chromiumcodereview, and our site format, but we can be flexible. For details on how to format your article, 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 Guidelines for Dart Doc Comments and, if you’re contributing to DOM-related docs such as dart:html, ContributingHTMLDocumentation.
- 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.
Sign Google's contributor license agreement before you send us any contributions. (If you're a Google employee, you can skip this step.)
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.
Just file a bug with Docs-* type and/or Area-Site.
Some authors like to create the article in a Google Drive document, moving to Markdown once the majority of comments have been dealt with.
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.)
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.
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.
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:
- Go to src/site/authors.
- Copy seth-ladd.html to your-name.html.
- 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.
- Edit index.html to add your name (alphabetically by first name).