Re-write web site copywriting

baoshan · Jul 1, 2012 · 95327a6 · 95327a6
1 parent e886fdf
commit 95327a6
Show file tree

Hide file tree

Showing 2 changed files with 96 additions and 103 deletions.
diff --git a/copywriting/features.md b/copywriting/features.md
@@ -29,7 +29,7 @@ with source automatically. So your documentation will be always up-to-date.
 
 ## Become a Better Developer Right Now
 
-  * Include a concise description for all folders and source files.
+  * Architecturing the Project Include a concise description for all folders and source files.
 
     + For source files, write the description at the first line as:
           {COMMENT_SYMBOL}{FOUR SPACES}{THE DESCRIPTION}
@@ -44,19 +44,20 @@ with source automatically. So your documentation will be always up-to-date.
 
     + Break large, complex tasks into many small, simple, and intuitive tasks.
     + Write down each task's procedure using markdown in comments.
-    + Using docas.io to communicate the design with your team.
-    + Coding will become a breeze once your ideas got proofed.
+    + Communicate your design in docas generated documents with your team.
+    + Coding will be a breeze when your ideas get into shape.
 
-  * Judge the sanity of your design by analysing source lines of code.
+  * Judge the Sanity of Design by analysing source lines of code.
 
-    + Tackle down the puzzle piece by piece.
-    + Control the source lines of code of all sources under a maintaibable size.
+    + Tackle the puzzle down piece by piece.
+    + Keep source lines of code under a maintaibable size.
 
-  * Maintain always up-to-date documentations using docas.io.
+  * Maintain Up-to-Date Documents using Docas
 
-    + In two steps, have an always up-to-date documentation hosted at GitHub pages.
-    + Read the source by yourself.
-    + Invite your friends to use or comment on the source.
+    + Time spent will be rewarded when the code is maintained or enhanced.
+    + Rewards can come either from you or your team.
+    + Read your own source code, Luke!
+    + Invite friends to review your work.
 
 ## Supported Languages
 

diff --git a/copywriting/web.md b/copywriting/web.md
@@ -1,52 +1,99 @@
+## Introducing Docas
 
+Docas is an automatic documentation service which not only documents your GitHub
+repo on GitHub pages, but also keeps them up-to-date when new commits are pushed
+to GitHub.
 
-
-
-
-##Stop Doing
-Falling into the deep sea of the code，to find what you want for a long time!
+## How Docas Works
 
-Confusing what is a function of some code fragments has been compiled by yourself or by others!
+Every time you push to GitHub, docas automatically synchronizes documents hosted
+at GitHub pages. Source files and documents are different branchs (`master`
+and `gh-pages` accordingly) of the same repo.
 
-Repeatedly describing and testing some codes to your partners!
-
-
-#Let the code talks with you!
-
-Literate Programming can be Quicker and Dirtier.    
-
-
-
-##Who's Docas.io
-Docas.io automatically documents your GitHub repo which will be parsed as markdown to ensure 
-legibility, understandability, findability and also semantization on GitHub pages.
+The always up-to-date document site by default locates at:
+
+    your_github_login.github.com/your_repository_name
+
+will include:
+
+  1. **A project page.** The place not only perfect for keeping great ideas,
+  but also help forming better architecture by including effective description
+  for every folder and source code.
+
+  2. **Source code documents.** Comments in markdown will be rendered with your
+  code side-by-side to help you approach a better *literate-style* programming.
+
+## One-Time Setup
 
-Every time you push new commits to GitHub, docas keeps the master branch (the source codes)
-and gh-pages branch (the documentation) in sync.
+  1. Add `docas` as your collaborator.
+  2. Add service hook `http://docas.io` from the [admin panel].
+  3. You're there!
+    - Test it with any push or press the **Test Hook** button.
+    - First build takes longer than following synchronizations.
 
+[admin panel]: https://help.github.com/articles/post-receive-hooks
+
+## Being Smarter
+
+  * Start Last, Finish First!
+
+    + Do top-down and orthogonal design before coding the first line.
+    + Break large, complex tasks into small, simple, intuitive, and orthogonal
+    tasks.
+    + Design every task's detail in plain English and markdown.
+    + *According feature:* Docco (markdown and highlighted code side-by-side.)
+    + *According feature:* Browsing markdown in the project page.
+
+  * Communicate Well
 
-##How Docas.io Works
-Comments will be rendered with your code side by side to encourage literate programming styled
-development. Content of comments will be parsed as markdown to ensure readability, legibility, 
-and also Semantization.
+    + Include a concise description for every folder and source file.
+    + Shape your ideas and communicate with your team using docas.
+    + *According feature:* Description for folders and files.
+
+  * Stay Focused When Coding
+
+    + Uncompromised engineering finally proofs your ideas.
+    + Balance your design by keeping source lines of code under a maintaibable
+    size.
+    + Docas let code speaks for itself!
+    + *Counterpoint feature:* SLOC statistics.
+
+  * Keep Documents Fresh
+
+    + Your time spent will be rewarded when code is maintained or enhanced.
+    + Rewards come both from yourself and your team.
+    + *According feature:* GitHub push synchronization.
 
-Literate comments will help you be easier to understand and find the source code.
+  * Release It!
 
-It looks like talk with you in our familiar language. 
+    + Set another exciting goal to motivate yourself.
+    + Have a party with your team!
+    + *According feature:* Try docas (beta) now!
 
-Docas.io automatically generates html documents using docco for all sources, plus a cover
-page (named `index.html` by default) for your GitHub repo automatically.
+## Supported Languages
 
-Generated documents will be hosted using GitHub pages in the same repository
-which can be accessed from:
+  * JavaScript
+  * CoffeeScript
+  * Ruby
+  * Python
+  * Perl
+  * Shell
+  * And suggest your favorite!
 
-    http://your_github_login.github.com/your_repository_name
+## Recycle Bin
 
-Each time you push new commits to GitHub, docas.io synchronizes the documents with source 
-automatically. So the documents will be always up-to-date.
+## Feature
 
+    + For source files, write the description at the first line as:
+          {COMMENT_SYMBOL}{FOUR SPACES}{THE DESCRIPTION}
+    + For markdown files, write the description at the first line as:
+          {FOUR SPACES}{THE DESCRIPTION}
+    + For directories, the description is the description for the `README.md` in
+    that directory.
+    + For shebang scripts, write the description as source files following the
+    shebang line. 
 
-##Reasons of falling in love with your code 
+## Reasons of falling in love with your code 
 
   *  __Legibility__    
 Comments will be rendered with your code side by side. 
@@ -75,64 +122,9 @@ understand the program construction process.
 
   * Be good for thinking, and to all view the code from a higher level. 
 
-###For  R&D Team
-  * The required source code will be quickly find by your partners for using and improvement.
-
-  * Enhance the efficiency of the project development and follow-up maintenance. Avoid the influence 
-of personnel changes or other factors leads to efficiency low and maintenance difficulties.
-
-
-## Steps to Enjoying Docas.io
-
-* Classic Method
-
-  1. Open your repo on GitHub and go to its admin page.
-  2. Add `docas` as your collaborator.
-  3. Add the service hook at `http://docas.io` from the [admin panel] of your repo.
-  4. Test it with any push. The initial build may takes longer than following pushes.
-  5. You are done. A web interface is planned.
-
-[admin panel]: https://help.github.com/articles/post-receive-hooks
-
-* A Web Inferface is Planned
-
-## Become a Better Developer Right Now
-
-  * Include a concise description for all folders and source files.
-
-    + For source files, write the description at the first line as:
-          {COMMENT_SYMBOL}{FOUR SPACES}{THE DESCRIPTION}
-    + For markdown files, write the description at the first line as:
-          {FOUR SPACES}{THE DESCRIPTION}
-    + For directories, the description is the description for the `README.md` in
-    that directory.
-    + For shebang scripts, write the description as source files following the
-    shebang line. 
-
-  * Always do top-down design before coding.
-
-    + Break large, complex tasks into many small, simple, and intuitive tasks.
-    + Write down each task's procedure using markdown in comments.
-    + Using docas.io to communicate the design with your team.
-    + Coding will become a breeze once your ideas got proofed.
-
-  * Judge the sanity of your design by analysing source lines of code.
-
-    + Tackle down the puzzle piece by piece.
-    + Control the source lines of code of all sources under a maintaibable size.
-
-  * Maintain always up-to-date documentations using docas.io.
-
-    + In two steps, have an always up-to-date documentation hosted at GitHub pages.
-    + Read the source by yourself.
-    + Invite your friends to use or comment on the source.
+##Stop Doing
+Falling into the deep sea of the code，to find what you want for a long time!
 
-## Supported Languages
+Confusing what is a function of some code fragments has been compiled by yourself or by others!
 
-  * JavaScript
-  * CoffeeScript
-  * Ruby
-  * Python
-  * Perl
-  * Shell
-  * And suggest your favorite!
+Repeatedly describing and testing some codes to your partners!