Step one towards stable error messages with details:

pkg/observe/lib/src/messages.dart

+// Copyright (c) 2014, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+/// Contains all warning messages produced by the observe transformer.
+library observe.src.messages;
+
+import 'package:code_transformers/messages/messages.dart';
+
+const noObservableOnLibrary = const MessageTemplate(
+    const MessageId('observe', 1),
+    '@observable on a library no longer has any effect. '
+    'It should be placed on individual fields.',

[Kathy Walrath, 2014/09/03 19:36:05]

It should... fields.
->
Instead, annotate individual fields as @observable.
[GLOBAL]

[Siggi Cherem (dart-lang), 2014/09/04 02:32:14]

Done.

+    '`@observable` on a library is not supported.',

[Kathy Walrath, 2014/09/03 19:36:06]

These messages have a slightly different format from the other messages. To make
these consistent, I'll take out the verb and the terminating ".", and (for
consistency within this group) make the object plural.

->
'`@observable` not supported on libraries',

[Siggi Cherem (dart-lang), 2014/09/04 02:32:14]

Done.

+    _COMMON_MESSAGE_WHERE_TO_USE_OBSERVABLE);
+
+const noObservableOnTopLevel = const MessageTemplate(
+    const MessageId('observe', 2),
+    'Top-level fields can no longer be observable. '
+    'Observable fields should be put in observable objects.',
+    '`@observable` on top-level fields is not supported.',

[Kathy Walrath, 2014/09/03 19:36:05]

->
'`@observable` not supported on top-level fields',

[Siggi Cherem (dart-lang), 2014/09/04 02:32:15]

Done.

+    _COMMON_MESSAGE_WHERE_TO_USE_OBSERVABLE);
+
+const noObservableOnClass = const MessageTemplate(
+    const MessageId('observe', 3),
+    '@observable on a class no longer has any effect. '
+    'It should be placed on individual fields.',
+    '`@observable` on classes is not supported.',

[Kathy Walrath, 2014/09/03 19:36:06]

->
'`@observable` not supported on classes',

[Siggi Cherem (dart-lang), 2014/09/04 02:32:14]

Done.

+    _COMMON_MESSAGE_WHERE_TO_USE_OBSERVABLE);
+
+const noObservableOnStaticField = const MessageTemplate(
+    const MessageId('observe', 4),
+    'Static fields can no longer be observable. '
+    'Observable fields should be put in observable objects.',

[Kathy Walrath, 2014/09/03 19:36:05]

should be put in -> must be in
[GLOBAL]

[Siggi Cherem (dart-lang), 2014/09/04 02:32:14]

Done.

+    '`@observable` on static fields is not supported.',

[Kathy Walrath, 2014/09/03 19:36:05]

->
'`@observable` not supported on static fields',

[Siggi Cherem (dart-lang), 2014/09/04 02:32:14]

Done.

+    _COMMON_MESSAGE_WHERE_TO_USE_OBSERVABLE);
+
+const requireObservableInterface = const MessageTemplate(
+    const MessageId('observe', 5),
+    'Observable fields should be put in an observable '

[Kathy Walrath, 2014/09/03 19:36:05]

an observable -> observable

[Siggi Cherem (dart-lang), 2014/09/04 02:32:15]

Done.

+    'objects. Please declare that this class extends from '

[Kathy Walrath, 2014/09/03 19:36:06]

Please declare -> Change this class to extend, include, or implement Observable.

[What does "include Observable" mean?]

[Siggi Cherem (dart-lang), 2014/09/04 02:32:14]

include -> mixin

+    'Observable, includes Observable, or implements '
+    'Observable.',
+    '`@observable` must be used on a class that implements `Observable`.',

[Kathy Walrath, 2014/09/03 19:36:06]

->
'`@observable` field not in an `Observable` class',

[Siggi Cherem (dart-lang), 2014/09/04 02:32:14]

Done.

+    _COMMON_MESSAGE_WHERE_TO_USE_OBSERVABLE);
+
+const String _COMMON_MESSAGE_WHERE_TO_USE_OBSERVABLE = '''
+Long ago `@observable` was supported on classes, libraries, and even top-level
+declarations and static fields. Today, the annotation has no effect on these
+elements. Only instance fields on `Observable` classes are supported, and you
+must explicitly opt-in on each field you wish to make observable. 

[Kathy Walrath, 2014/09/03 19:36:06]

I'm not crazy about having the same text for each message. I spent a little time
looking at the page to make sure they didn't differ. It might be better to have
the common message at the top, directly under "Messages from package observe".

If we keep the common message:

Only instance fields on `Observable` classes can be observable,
and you must explicitly annotate each observable field as `@observable`.

(That started as just changing "opt-in" to "opt in", but then I realized "opt
in" might not be clear. It has too many uses of the word "observable", but I
couldn't think of a clearer way to say it.)

[Siggi Cherem (dart-lang), 2014/09/04 02:32:15]

Done. Yeah, I'm not a fan of repeating the message either, but right now I have
no support for package-level docs, just details for each individual message.

Maybe for v2? :)

+''';