README.md in brief-0.0.5 vs README.md in brief-1.0.0

@@ -1,71 +1,172 @@
-# Brief
+# Brief 
 
-Brief is a tool to make writing markdown more productive. You can think
-of it like a preprocessor for markdown.   
+An ActiveRecord style layer on top of a folder of markdown files.
 
-Brief converts raw markdown into a nested structure which can be
-used to automate tasks and generate more specific content elements. 
+### No more dead documents 
 
-Based on which headings you use and how you nest them, brief 
-will allow you to define mappings to objects which can be used to
-automate other tasks.  
+Brief is a tool that lets you build simple applications on top of
+collections of markdown files.  The metaphor we use is a briefcase,
+which contains folders with different document types.
 
-I personally use the brief tool to allow me to take a single markdown
-file and create a project wiki page, with links to related milestones
-and github issues.
+Every document type, or model, can define a simple schema of attributes, 
+which can be specified in a YAML frontmatter preamble at the very top of
+each document.  
 
-Example:
+In addition to frontmatter metadata, you can declare other model
+attributes as CSS selectors.  For example, the very first h1 heading
+could be the title for your document, and the corresponding model for
+that document would have a `title` method which returned its value.
 
-```markdown
-# Wiki Page Heading
+This is a great way to build applications whose primary interface is the
+text editor, allowing writing and thought to flow as freely as possible
+and to later be used to power some automation tasks.
 
-Content. Will go on a wiki page.  The content below here,
-and the subheadings, will be replaced with a roll-up / summary 
-of the elements.
+**Think of it as an ActiveRecord like layer on top of a folder of
+Markdown files**.  Brief turns static text into a 'living' data object.
 
-## Milestone Heading
+## Getting started 
 
-This content will go in the milestone body.  The wiki page
-that this belongs to, will include a different kind of view of this
-content.
+```bash
+gem install brief
+mkdir blog
+cd blog 
+brief init
+```
 
-### An issue title
+This will create a new folder for your briefcase, along with the
+following config file and structure.
 
-This goes in the issue's body. The wiki page this belongs to will
-possibly have a link to the issue and a label for its status.
+```
+- docs/
+  - an-introduction-to-brief.html.md
+- models/
+- brief.rb
+```
 
-### Another issue title
+The config file will look like:
 
-This goes in this issue's body.  Same thing. It obviously belongs to the
-milestone.
+```ruby
 
+# configuration options for this briefcase
+config do
+  set(:models_path => Pathname(__FILE__).parent.join("models"))
+end
+
+# define a Post model
+define("Post") do
+
+  # the post model will have YAML frontmatter 
+  # with values for 'status' and 'date'
+  meta do
+    status
+    date DateTime, :default => lambda {|post, attr| post.document.created_at }
+  end
+  
+  # the post model will have a 'title' method which returns the text
+  # from the first h1 heading
+  content do
+    title "h1"
+    has_many :subheadings, "h2"
+  end
+
+  helpers do
+    def publish(options={})
+
+    end
+  end
+  
+  # Whenever we call post.save() and the status attribute changes
+  # from draft to published, do something with the model
+  on_status_change(:from => "draft", :to => "published") do |model|
+    # Do Something
+    # mail_service.send_html_email_campaign(model.to_html)
+  end
+end
+
+# this creates a custom command in the brief CLI tool
+#
+# so when you run:
+# 
+#   brief publish posts /path/to/*.html.md.
+#
+# the brief CLI will find models for the post files you reference,
+# and call whatever methods you want.
+
+action "publish posts" do |briefcase, models, options|
+
+  say "== Publishing #{ models.length } posts"
+
+  Array(models).each do |post|
+    post.publish()
+  end
+end
 ```
 
-Given the example above, I run:
+### Real World Application
 
+My company Architects.io, Inc. uses brief to power our Blueprint
+software.  A Blueprint is a collection of related documents that are
+used in the software architecture and design process, as well as in the
+day to day writing that takes place while building the software itself.
+
+This includes things like:
+
+- daily standups
+- bug reports
+- code reviews
+- feature epics
+- user stories
+- integration tests
+- release notes
+- wireframe annotations
+
+All of these things are simple markdown files.  They live in the
+projects we are working on, and by treating our writing as a structured
+exercise we are able to do a lot more things with it than just read it.
+
+For example we can do:
+
 ```
-brief publish project overview /path/to/markdown
+brief publish user stories /path/to/user-stories/*.html.md
 ```
 
-This will create a Github Wiki entry in the repo that I specify, and
-this wiki entry will include links to the milestones and issues. 
+which is implemented by:
 
-You can see a sample of this Wiki page here:
-(TODO INSERT LINK)
+```ruby
+# brief.rb
 
-### Publishing Briefs
+define "User Story" do
+  meta do
+    status
+  end
 
-Publishing a brief allows you to run some publishing tasks using raw
-markdown input.  
+  content do
+    title "h1"
+    paragraph "p:first-child"
+    persona "p:first-child strong:1st-child"
+    behavior "p:first-child strong:2nd-child"
+    goal "p:first-child strong:3rd-child"
+  end
 
-(TODO) show some examples of a publisher
+  helpers do
+    def create_github_issue
+      issue = github.create_issue(title: title, body: document.content)
+      set(issue_number: issue.number)
+    end
+  end
+end
 
-### Writing Briefs
+action "publish user stories" do |briefcase, models, options|
+  user_stories = models
 
-Writing a brief is as easy as running the brief command, with the name
-of the template you intend to use.  It will open up $EDITOR for you with
-some example input.
-
-```bash
-brief write project overview #=> Opens up $EDITOR with some example content in it
+  user_stories.each do |user_story|
+    if user_story.create_github_issue()
+      user_story.status = "published"
+      user_story.save
+    end
+  end
+end
 ```
+
+As you can see, Brief can be a way to make your Markdown writing efforts
+much more productive.