DevGuide guide for Authors

How to write a Developer’s Guide topic page.

The Dev Guide purpose is to lead the developer-reader to a feeling of pleasurable competence in Angular2. It does not strive to be comprehensive nor reveal every capability of the product.

The Reader

The Dev Guide has a target reader. You are not the target reader. The target reader ...

• is a competent, front-end JavaScript application developer with 1-2 years of JavaScript
• would like to use Angular 2 if it seems useful and easy enough to learn
• would like to be your friend and treat you to a beer
• is busy with a day job
• will read the guide by choice in his/her own free time
• wants to put Angular 2 to practical use as soon as possible
• is more likely to be building a business application than a mass-market product
• either lacks computer science training or has forgotten most of it
• is marginally interested in architectural purity
• does care about doing things “the right way”
• would happily accept guidance on what “the right way” is.

Now imagine that you are face-to-face with this reader in a conversation about Angular 2.

You’d want your side of the conversation to be friendly, practical, plain spoken, fun, and easy to consume in short doses. Write your chapter with that conversation in mind.

We’re not talking down to the reader. Although the target reader is not you, you should be interested in this guide too and have a good time reading it.

The primary reader has limited-to-no TypeScript experience but is willing to read examples in TypeScript and hopes to learn it.

An important secondary reader has no TypeScript experience and intends to write only in ES5.

The reader probably has Angular 1 experience but we will not assume that and we should avoid references to Angular 1. A serious mapping between the two products is a great idea but out of scope for the Dev Guide. If we decide that we really must compare an Angular 2 technique to something in Angular 1 we will should do so only in a brief aside.

Preparing an Outline

What is the readers journey through your topic. TOC is a linked TOC and here is where you lay your outline. Lay it out so you know where you are going even if you keep tweaking it as you go along. We strongly recommend have sample first, and then write content around it. Develop them in parallel. However, every chapter must have a sample.

Chapter structure

• Begin with a high-level statement of purpose and value. Readers must  know why they are reading this chapter within a sentence or two.

• Tell a story from start to finish.

• Speak conversationally. We (the author and the reader) are traveling together through the story.

• The story should flow in small chunks.

• Each chunk starts with a problem followed by an illustration of that problem, then a solution, and from there to a short explanation of that solution. Then lead “naturally” to a successor problem.

• Start from the most simple and compelling application problem and graduate to harder problems. The chapter is a winner if it seems like each new problem and solution is as easy as the one before.

• Avoid digression into corner cases and all the cool things that the feature can do. Until you find a clear and simple scenario for a capability, don’t try to explain it in the DevGuide. Ask an Angular core team member for help in finding that compelling scenario.

• Prefer problems+solutions to concepts. Let the concept emerge from the solution. Give the concept no more than the necessary “elevator pitch”.

• Do not start with architecture or technology.

• Do not engage in lengthy architectural discussions unless your chapter is a chapter on architecture ( which few are).

  It is ok to have an architectural review near the end in a clearly marked section for this purpose.  The reader can chose to opt out at that point. We’re trying to get the reader productive as quickly as possible and lots of theory up front gets in the way.

If you’ve told the story well, the readers will beg to know the architecture. Tell them then, not upfront.

• Conclude with a summary of key points/take-aways.
• Point to the recommended next step in the learning path
• We encourage ending with a “Frequently Asked Questions” section at the bottom of the chapter.

Identifying Goals

A good goal highlights the reader’s need in a sympathetic way.

Good goal: We will display information to users and receive their input.

Bad goal: You will learn about Form Template syntax

This is bad because it ignores the user’s perspective and boasts about our libraries. The “You” in this sentence creates an unpleasant and unnecessary distance between the author and the reader.

Outlining your chapter

State the theme for the chapter.  This helps others reviewing your chapter compare the content you create against the goal.  If appropriate, this may appear in the final text as a way to prepare the reader for what they'll know by the end of the chapter.

Create an outline of concepts that build toward the final goal.  Outline should not appear in final text but this is for you to ensure your ideas flow in a logical order and can be easily understood by folks who aren't familiar with the topic.

Programming Language: Write your concepts and examples for a TypeScript audience. At a later date, a second version will be created for JavaScript.  The Dart version is being developed in parallel by a specific team.

Vocabulary: We must present a single set of terminology for concepts, processes, entities, etc. in the world of Angular.  We have a glossary doc with the canonical list of terms and definitions used throughout documentation.  Please read this before starting.  Feel free to add and amend terminology here, but request a review on your addition before considering it complete. 

Avoid jargon. Look for a more familiar term drawn from everyday life.

We agree that a technical term can be more concise and precise to those who know that term (e.g. “pub/sub” or “Separation of Concerns”). It is ok to to relate your simpler language to a technical term or pattern in an aside.

Introductory paragraphs:  Give readers necessary background and set the context for the chapter.

For each concept

• Use asides to describe the [additional] benefits users get by following these recommendations

• Start with an example to make the problem concrete.

End a section with suggestions on where to go next for additional learning.

Writing Style 

• Prefer active voice. "Angular updates the DOM" is better than "The DOM gets updated" because it makes Angular feel less magical. Using specific components/services as the actor in your sentence is even better.

• Do use "we" and "us."

• Prefer present tense.

• Avoid gendered languages – use they/them/their over he/she.

• Avoid weasel words and clichés like "usually" (describe how often, or when/why things differ), "it can be said that" (adds no meaning), and "probably" (weakens meaning). You can use write-good to check for these problems.

• When writing recommendations for “best practices”, use the words:

• “Do”  - should almost always follow; you better have a great reason not to

• “Consider” - strongly preferred; deviate when you have a decent reason

• “Do not”  - should almost never do this; you better have a great reason.

• “Avoid” - strong aversion; deviate when you have a decent reason

If a recommendation is weaker than these verbs convey, it isn’t really a recommendation. Don’t bother listing it among “best practices”.

• All recommendations must include a “why”. You can reference outside material that you’ve summarized in a sentence.
• All recommendations must include at least one example.

Languages names

Always use the full name of a programming language, not its acronym. Write  “TypeScript” not “TS”.  Write “JavaScript”, not “JS” or “ES5”.  The acronyms “CSS” and “HTML” are ok.

Graphics

[TBD]

Favor simple flat geometric shapes without shadows or gradients

Backgrounds and borders from a limited pallette [TBD]

Avoid diagrams with more than 5 boxes

One- or two-word centered labels are best

The typeface for code is consolas

The typeface for text is arial

No trademarked images, icons or content

Coding Style

Every code example in a document must be supported by unit tests.  Every build of Angular will run those tests, ensuring that we have valid code in docs for every release.

File names must be in all lower case. Use dashes to separate words, e.g, hero-editor-component.ts.

Code snippets and examples use 2 spaces (not tabs) for each horizontal indentation level.

Vertical white space improves readability. Use it plentifully although no more than 2 lines of whitespace at a time.

Comments are fine when they focus the reader’s attention and explain the unobvious

Good comments:

// The application fails silently if we omit the next line

// TODO: re-factor into a separate service

// Simplistic way to break the fizzbuzz into smaller bongle-dogs

// Demo only. Insecure. Don’t do this in production code

Bad comments:

        // Sets the foo property

[more coding style guidelines coming]

Contributing and Conventions

The angular.io project uses commit message conventions when it comes to contributions. The conventions are used in the AngularJS and the Angular 2 project. Tools are then used to generate changelogs for the project automatically. The commit message conventions can be found here: https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit

Please use these conventions when shaping commits as contribution to the project.

Asking Questions

Please ask questions if you get stuck. If we haven’t already done so, ping [email protected] (or [email protected])  to get added to the docs-authoring channel on Slack. Use Slack for asking for reviews, quick questions, and other communication with the core team members and writers who are working on the docs.