doc updates

README.md

@@ -7,15 +7,6 @@ request or found a bug, please file it at the [issue tracker][].
 
 [issue tracker]: https://github.com/memspace/zefyr/issues
 
-### Documentation
-
-* [Quick Start](doc/quick-start.md)
-* [Data Format and Document Model](doc/concepts/data-and-document.md)
-* [Style attributes](doc/concepts/attributes.md)
-* [Heuristic rules](doc/concepts/heuristics.md)
-* [Images](doc/images.md)
-* [FAQ](doc/faq.md)
-
 ## Clean and modern look
 
 Zefyr's rich text editor is built with simplicity and flexibility in
@@ -45,7 +36,7 @@ collaborative editing use cases or whenever there is a need for
 conflict-free resolution of changes.
 
 > Zefyr editor uses Quill.js **Delta** as underlying data format. Read
-> more about Zefyr and Deltas in our [documentation](doc/data-and-document.md).
+> more about Zefyr and Deltas in our [documentation](doc/concepts/data-and-document.md).
 > Make sure to checkout [official documentation][delta] for Delta format
 > as well.
 

doc/concepts/attributes.md

@@ -1,7 +1,7 @@
 ## Style Attributes
 
 > If you haven't yet, read introduction to Zefyr document model called
-> Notus [here](data-and-document.md);
+> Notus [here](data-and-document.md).
 
 Style attributes in Notus documents are simple key-value pairs, where
 keys identify the attribute and value describes the style applied, for

doc/concepts/data-and-document.md

@@ -18,7 +18,7 @@ essentially JSON, and is human readable.
 [Delta]: https://quilljs.com/docs/delta/
 [ot]: https://en.wikipedia.org/wiki/Operational_transformation
 [github-delta]: https://github.com/quilljs/delta
-[pub-delta]: https://pub.dartlang.com/packages/quill_delta
+[pub-delta]: https://pub.dev/packages/quill_delta
 
 ### Deltas quick start
 

doc/concepts/heuristics.md

@@ -11,15 +11,13 @@ a new list item when user presses `Enter` key.
 In Notus (document model used by Zefyr editor), such rules are called
 *heuristic rules*. There are two main purposes for heuristic rules:
 
-1. User experience: rules like above-mentioned autoformatting of links
-   are here to make editing a user friendly process.
-2. Semantics preservation: this is mostly invisible for the user but
-  is very important nevertheless. There is a set of rules to make sure
-  that a document change conforms to the data format and model
-  semantics.
+1. User experience: rules like above-mentioned autoformatting of links are here to make editing a user friendly process.
+2. Semantics preservation: this is mostly invisible for the user but is very important nevertheless. There is a set of rules to make sure that a document change conforms to the data format and model semantics.
 
 Let's cover the second item in more detail.
 
+### Example heuristic rule
+
 Say, a user is editing following document (cursor position is indicated
 by pipe `|` character):
 
@@ -39,7 +37,8 @@ var change = doc.format(
 ```
 
 If we try to apply this change as-is it would have no effect or, more
-likely, result in an `AssertionError`. This is why all methods in
+likely, result in an `AssertionError` because we are trying to apply line style
+to a character in the middle of a line. This is why all methods in
 `NotusDocument` have an extra step which applies heuristic rules to
 the change (there is one method which skips this step, `compose`,
 read more on it later) before actually composing it.
@@ -62,13 +61,13 @@ what user intended to do.
 There are more similar scenarios which are covered by heuristic rules
 to ensure consistency with the document model and provide better UX.
 
-### `NotusDocument.compose()` and skipping heuristic rules.
+### `NotusDocument.compose()` and skipping heuristic rules
 
 The `compose()` method is the only method which skips the step of
 applying heuristic rules and therefore **should be used with great
 care** as it can result in corrupted document state.
 
-Use this method when you sure that the change you are about to compose
+Use this method when you are sure that the change you are about to compose
 conforms to the document model and data format semantics.
 
 This method exists mostly to enable following use cases:

doc/faq.md

@@ -1,6 +1,6 @@
 ## Frequently asked questions
 
-### Are Notus documents compatible with Quill documents?
+### Q: Are Notus documents compatible with Quill documents?
 
 Short answer is no. Even though Notus uses Quill Delta as underlying
 representation for its documents there are at least differences in

doc/quick-start.md

@@ -1,10 +1,11 @@
 ## Quick Start
 
-Zefyr project is split in two main packages:
+Zefyr project consists of two packages:
 
-1. `zefyr` - Flutter package which provides the UI part
-2. `notus` - platform-agnostic package which provides document model
-   used by `zefyr` package.
+1. [zefyr](https://pub.dev/packages/zefyr) - Flutter package which provides
+   the UI part.
+2. [notus](https://pub.dev/packages/notus) - platform-agnostic package which
+   provides document model used in Zefyr editor.
 
 ### Installation
 
@@ -25,7 +26,7 @@ There are 4 main objects you would normally interact with in your code:
 * `NotusDocument`, represents a rich text document and provides
   high-level methods for manipulating the document's state, like
   inserting, deleting and formatting of text.
-  Read [documentation][data_and_docs] for more details on Notus
+  Read [documentation](concepts/data-and-document.md) for more details on Notus
   document model and data format.
 * `ZefyrEditor`, a Flutter widget responsible for rendering of rich text
   on the screen and reacting to user actions.
@@ -73,5 +74,5 @@ class MyWidgetState extends State<MyWidget> {
 }
 ```
 
-In following sections you will learn more about document
-model, Deltas, attributes and other aspects of the editor.
+This above is required minimum to include Zefyr in your Flutter app and start
+writing some rich text.