From 0aa0a7c05a78e9b29881570604c24381b658fe2a Mon Sep 17 00:00:00 2001 From: Jethro Kuan Date: Fri, 31 Jul 2020 02:15:42 +0800 Subject: [PATCH] (doc): Add target audience section (#990) --- README.md | 5 +++++ doc/org-roam.org | 32 ++++++++++++++++++++++++++++++++ doc/org-roam.texi | 35 +++++++++++++++++++++++++++++++++++ 3 files changed, 72 insertions(+) diff --git a/README.md b/README.md index bd65dd9..786b42d 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,11 @@ ## Synopsis +> **NOTE:** Org-roam builds upon Emacs and Org-mode, both of which are intricate +> tools that require time investment for mastery. This makes Org-roam less +> friendly for beginners, but extremely powerful for those familiar with the +> ecosystem, or willing to invest effort in it. + Org-roam is a [Roam][roamresearch] replica built on top of the all-powerful [Org-mode][org]. diff --git a/doc/org-roam.org b/doc/org-roam.org index e493a46..a74cce4 100644 --- a/doc/org-roam.org +++ b/doc/org-roam.org @@ -56,6 +56,38 @@ Org-roam provides several benefits over other tooling: - Leverages the Org-mode ecosystem :: Over the years, Emacs and Org-mode has developed into a mature system for plain-text organization. Building upon Org-mode already puts Org-roam light-years ahead of many other solutions. - Built on Emacs :: Emacs is also a fantastic interface for editing text, and we can inherit many of the powerful text-navigation and editing packages available to Emacs. +* Target Audience + +Org-roam is a tool that will appear unfriendly to anyone unfamiliar with Emacs +and Org-mode, but is also extremely powerful to those willing to put effort in +mastering the intricacies of the tools. Org-roam stands on the shoulders on +giants. Emacs was first created in 1985, and remains a top tier tool for editing +text and designing textual interfaces. The malleability of Emacs allowed the +creation of Org-mode, an all-purpose plain-text system for maintaining TODO +lists, planning projects, and authoring documents. Both of these tools are +incredibly vast and require significant time investment to master. + +Org-roam assumes basic familiarity with these tools. It is not difficult to get +up and running with basic text-editing functionality, but one will only fully +appreciate the power of building Roam functionality into Emacs and Org-mode when +the usage of these tools become more advanced. + +One key advantage to Org-roam is that building on top of Emacs gives it +malleability. This is especially important for note-taking workflows. It is our +belief that note-taking workflows are extremely personal, and there is no one +tool that's perfect for you. Org-mode and Org-roam allows you to discover what +works for you, and build that perfect tool for yourself. + +If you are new to the software, and choose to take this leap of faith, I hope +you find yourself equally entranced as Neal Stephenson was. + +#+BEGIN_QUOTE +Emacs outshines all other editing software in approximately the same way that +the noonday sun does the stars. It is not just bigger and brighter; it simply +makes everything else vanish. – Neal Stephenson, In the Beginning was the +Command Line (1998) +#+END_QUOTE + * A Brief Introduction to the Zettelkasten Method Org-roam provides utilities for maintaining a digital slip-box. This section diff --git a/doc/org-roam.texi b/doc/org-roam.texi index 7bc5442..ddbd60e 100644 --- a/doc/org-roam.texi +++ b/doc/org-roam.texi @@ -65,6 +65,7 @@ General Public License for more details. @menu * Introduction:: +* Target Audience:: * A Brief Introduction to the Zettelkasten Method:: * Installation:: * Getting Started:: @@ -186,6 +187,40 @@ Over the years, Emacs and Org-mode has developed into a mature system for plain- Emacs is also a fantastic interface for editing text, and we can inherit many of the powerful text-navigation and editing packages available to Emacs. @end table +@node Target Audience +@chapter Target Audience + +Org-roam is a tool that will appear unfriendly to anyone unfamiliar with Emacs +and Org-mode, but is also extremely powerful to those willing to put effort in +mastering the intricacies of the tools. Org-roam stands on the shoulders on +giants. Emacs was first created in 1985, and remains a top tier tool for editing +text and designing textual interfaces. The malleability of Emacs allowed the +creation of Org-mode, an all-purpose plain-text system for maintaining TODO +lists, planning projects, and authoring documents. Both of these tools are +incredibly vast and require significant time investment to master. + +Org-roam assumes basic familiarity with these tools. It is not difficult to get +up and running with basic text-editing functionality, but one will only fully +appreciate the power of building Roam functionality into Emacs and Org-mode when +the usage of these tools become more advanced. + +One key advantage to Org-roam is that building on top of Emacs gives it +malleability. This is especially important for note-taking workflows. It is our +belief that note-taking workflows are extremely personal, and there is no one +tool that's perfect for you. Org-mode and Org-roam allows you to discover what +works for you, and build that perfect tool for yourself. + +If you are new to the software, and choose to take this leap of faith, I hope +you find yourself equally entranced as Neal Stephenson was. + +@quotation +Emacs outshines all other editing software in approximately the same way that +the noonday sun does the stars. It is not just bigger and brighter; it simply +makes everything else vanish. – Neal Stephenson, In the Beginning was the +Command Line (1998) + +@end quotation + @node A Brief Introduction to the Zettelkasten Method @chapter A Brief Introduction to the Zettelkasten Method