Update & revise docs

+ Getting Started
  + Add "Using/loading local packages" section
  + Add "Pinning packages to specific commits" section
  + Clarify prereqs & revise install docs
  + Revise package-management section
+ FAQ
  + Add package management section

docs/contributing.org

@@ -32,19 +32,20 @@ to contribute to our fine corner of the interwebs.
 - [[#contributing-documentation][Contributing documentation]]
   - [[#contributing-to-dooms-manual][Contributing to Doom's manual]]
   - [[#contributing-module-documentation][Contributing module documentation]]
+- [[#help-keep-packages-up-to-date][Help keep packages up-to-date!]]
 - [[#other-ways-to-support-doom-emacs][Other ways to support Doom Emacs]]
 - [[#special-thanks][Special thanks]]
 
 * Where can I help?
 + Our [[https://github.com/hlissner/doom-emacs/issues][issue tracker]] has many issues. If you find one that you have an answer to,
-  please don't hold back!
+  it would be a huge help!
 + Look for issues tagged [[https://github.com/hlissner/doom-emacs/labels/good%20first%20issue][good first issue]]. These were judged to have a low
   barrier of entry.
 + Look for issues tagged [[https://github.com/hlissner/doom-emacs/labels/help%20wanted][help wanted]]. These tend to be a little (or a lot)
   harder, and are issues outside my own expertise.
 + If you've encountered a bug, [[https://github.com/hlissner/doom-emacs/issues/new/choose][file a bug report]].
 + The [[https://github.com/hlissner/doom-emacs/projects/3][development roadmap board]] is a rough timeline of what is being worked on
-  and when. It will give you some idea of what will change and where you can
+  and when. It will give you an idea of what will change and where you can
   redirect your efforts.
 + The [[https://github.com/hlissner/doom-emacs/projects/2][plugins under review board]] lists third party plugins being considered (or
   rejected) for inclusion in Doom Emacs. Approved and unclaimed packages are
@@ -54,30 +55,21 @@ to contribute to our fine corner of the interwebs.
   cause) perhaps you can address them at the source.
 
 * TODO Reporting issues
-So you've found a problem. Before you fire off that bug report, there are a few
+You've found a problem and you're ready to fire off that bug report. Hold up!
-things you should try first:
+Before you do that, [[file:getting_started.org::*Troubleshoot][have a look at our Troubleshooting guide]]. If none of these
+suggestions pan out, /then/ it is time to file a bug report.
 
-+ Make sure your configuration (or Doom Emacs) is *not* byte-compiled. Run ~doom
+An effective bug report is informative. Please try to provide:
-  clean~ to ensure it isn't. *Byte-compilation interferes with debugging!*
-+ Run ~bin/doom refresh~ to ensure all plugins are installed and autoload files
-  generated.
-+ Run ~bin/doom doctor~ to diagnose common issues with your system.
-+ Check [[file:faq.org::*Common%20Issues][Common Issues]] in the FAQ to see if yours is a known issue.
-+ If you happen to know what module(s) are relevant to your issue, check their
-  documentation (press =<leader> h m= to jump to a module's documentation). Your
-  issue may be documented.
-+ If possible, check if the issue can be reproduced in vanilla Emacs (Emacs
-  without Doom) and/or vanilla Doom (Doom without your private config). To test
-  this, use ~M-x doom/sandbox~ (bound to =<leader> h E=). [[file:getting_started.org::*Use the sandbox][A guide for using the
-  sandbox can be found in the manual]].
-+ Make sure your issue hasn't already been reported by searching the [[https://github.com/hlissner/doom-emacs/issues][issue
-  tracker]].
-+ Make sure your issue hasn't been resolved on the =develop= branch of Doom.
 
-If these suggestions haven't worked for you, it's time [[https://github.com/hlissner/doom-emacs/issues/new/choose][to write a bug report]].
++ A backtrace of all mentioned errors.
-Please make sure of the following before you submit:
++ A step-by-step reproduction of the issue.
++ Information about your Doom config and system environment.
++ Screenshots/casts of the issue (if possible).
 
-** TODO Collect backtraces of any error messages
+This section will show you how to collect this information.
+
+** Acquire a backtrace from errors
+See "[[file:getting_started.org::*How to extract a backtrace from an error][How to extract a backtrace from an error]]" in the [[file:getting_started.org][Getting Started]] guide.
 
 ** TODO Create a step-by-step reproduction guide
 
@@ -165,6 +157,11 @@ contact via our [[https://discord.gg/bcZ6P3y][Discord server]] or [[mailto:henri
 
 ** TODO Contributing module documentation
 
+* TODO Help keep packages up-to-date!
+Doom pins all its packages to reduce the likelihood of upstream breakage leaking
+into Doom Emacs. However, we may miss when a package releases hotfixes for
+critical issues. Let us know or PR a bump to our pinned packages.
+
 * TODO Other ways to support Doom Emacs
 
 * TODO Special thanks

docs/faq.org

@@ -20,11 +20,6 @@
   - [[#should-i-fork-doom-to-customize-it][Should I fork Doom to customize it?]]
   - [[#how-do-i-configure-doom-emacs][How do I configure Doom Emacs?]]
   - [[#how-do-i-enable-or-disable-a-doom-module][How do I enable or disable a Doom module?]]
-  - [[#how-do-i-install-a-package-from-elpa][How do I install a package from ELPA?]]
-  - [[#how-do-i-install-a-package-from-githubanother-source][How do I install a package from github/another source?]]
-  - [[#how-do-i-change-where-an-existing-package-is-installed-from][How do I change where an existing package is installed from?]]
-  - [[#how-do-i-disable-a-package-completely][How do I disable a package completely?]]
-  - [[#how-do-i-reconfigure-a-package-included-in-doom][How do I reconfigure a package included in Doom?]]
   - [[#how-do-i-change-the-theme][How do I change the theme?]]
   - [[#how-do-i-change-the-fonts][How do I change the fonts?]]
   - [[#how-do-i-bind-my-own-keys-or-change-existing-ones][How do I bind my own keys (or change existing ones)?]]
@@ -39,6 +34,13 @@
   - [[#when-should-and-shouldnt-i-use-bindoom][When should and shouldn't I use ~bin/doom~?]]
   - [[#when-to-run-doom-sync][When to run ~doom sync~]]
   - [[#how-to-suppress-confirmation-prompts-while-bindoom-is-running][How to suppress confirmation prompts while ~bin/doom~ is running]]
+- [[#package-management][Package Management]]
+  - [[#how-do-i-install-a-package-from-elpa][How do I install a package from ELPA?]]
+  - [[#how-do-i-install-a-package-from-githubanother-source][How do I install a package from github/another source?]]
+  - [[#how-do-i-change-where-an-existing-package-is-installed-from][How do I change where an existing package is installed from?]]
+  - [[#how-do-i-disable-a-package-completely][How do I disable a package completely?]]
+  - [[#how-do-i-reconfigure-a-package-included-in-doom][How do I reconfigure a package included in Doom?]]
+  - [[#where-does-straight-clonebuild-packages-to][Where does straight clone/build packages to?]]
 - [[#defaults][Defaults]]
   - [[#why-ivy-over-helm][Why Ivy over Helm?]]
   - [[#why-are-there-no-default-keybinds-for-smartparens-for-evil-users][Why are there no default keybinds for Smartparens (for evil users)?]]
@@ -437,53 +439,6 @@ module list with Doom.
 See the "[[file:getting_started.org::*Configuration modules][Configuration modules]]" section of the [[file:getting_started.org][Getting Started]] guide for more
 information.
 
-** How do I install a package from ELPA?
-See the "[[file:getting_started.org::*Installing%20packages][Installing packages]]" section of the [[file:getting_started.org][Getting Started]] guide.
-
-** How do I install a package from github/another source?
-See the "[[file:getting_started.org::*Installing%20packages%20from%20external%20sources][Installing packages from external sources]]" section of the [[file:getting_started.org][Getting
-Started]] guide.
-
-** How do I change where an existing package is installed from?
-See the "[[file:getting_started.org::*Changing%20a%20built-in%20recipe%20for%20a%20package][Changing a built-in recipe for a package]]" section of the [[file:getting_started.org][Getting
-Started]] guide.
-
-** How do I disable a package completely?
-See the "[[file:getting_started.org::*Disabling%20packages][disabling packages]]" section of the [[file:getting_started.org][Getting Started]] guide.
-
-** How do I reconfigure a package included in Doom?
-~use-package!~ and ~after!~ (wrappers around ~use-package~ and
-~eval-after-load~, respectively) are your bread and butter for configuring
-packages in Doom.
-
-#+BEGIN_SRC elisp
-;; Takes a feature symbol or a library name (string)
-(after! evil
-  (setq evil-magic nil))
-
-;; Takes a major-mode, a quoted hook function or a list of either
-(add-hook! python-mode
-  (setq python-shell-interpreter "bpython"))
-
-(use-package! hl-todo
-  ;; if you omit :defer, :hook, :commands, or :after, then the package is loaded
-  ;; immediately. By using :hook here, the `hl-todo` package won't be loaded
-  ;; until prog-mode-hook is triggered (by activating a major mode derived from
-  ;; it, e.g. python-mode)
-  :hook (prog-mode . hl-todo-mode)
-  :init
-  ;; code here will run immediately
-  :config
-  ;; code here will run after the package is loaded
-  (setq hl-todo-highlight-punctuation ":"))
-
-;; There's also `setq-hook!' for setting variables buffer-locally
-(setq-hook! python-mode python-indent-offset 2)
-#+END_SRC
-
-See the "[[file:getting_started.org::*Configuring%20Doom][Configuring Doom]]" section of the [[file:getting_started.org][Getting Started]] guide for more
-explanation and examples.
-
 ** How do I change the theme?
 There are two ways to load a theme. Both assume the theme is installed and
 available. You can either set ~doom-theme~ or manually load a theme with the
@@ -755,6 +710,29 @@ doom --yes update
 YES=1 doom update
 #+END_SRC
 
+* Package Management
+** How do I install a package from ELPA?
+See the "[[file:getting_started.org::*Installing%20packages][Installing packages]]" section of the [[file:getting_started.org][Getting Started]] guide.
+
+** How do I install a package from github/another source?
+See the "[[file:getting_started.org::*Installing%20packages%20from%20external%20sources][Installing packages from external sources]]" section of the [[file:getting_started.org][Getting
+Started]] guide.
+
+** How do I change where an existing package is installed from?
+See the "[[file:getting_started.org::*Changing a recipe for a included package][Changing a recipe for a included package]]" section of the [[file:getting_started.org][Getting
+Started]] guide.
+
+** How do I disable a package completely?
+See the "[[file:getting_started.org::*Disabling%20packages][disabling packages]]" section of the [[file:getting_started.org][Getting Started]] guide.
+
+** How do I reconfigure a package included in Doom?
+See the "[[file:getting_started.org::*Configuring packages][configuring packages]]" section of the Getting Started guide.
+
+** Where does straight clone/build packages to?
+Straight clones packages to =~/.emacs.d/.local/straight/repos/REPO-NAME=, then
+later symlinks and byte-compiles them to
+=~/.emacs.d/.local/straight/build/PACKAGE-NAME= when they are "built".
+
 * Defaults
 ** Why Ivy over Helm?
 Short answer: ivy is simpler to maintain.

docs/index.org

@@ -45,6 +45,7 @@ s= (or =C-h d s=).
 ** [[file:faq.org][Frequently Asked Questions]]
 - [[file:faq.org::*General][General]]
 - [[file:faq.org::*Configuration][Configuration]]
+- [[file:faq.org::*Package Management][Package Management]]
 - [[file:faq.org::*Defaults][Defaults]]
 - [[file:faq.org::Common Issues][Common Issues]]
 - [[file:faq.org::Contributing][Contributing]]

docs/workflow.org

@@ -1,7 +1,15 @@
-#+TITLE: Workflow tips, tricks & tutorials
+#+TITLE: Getting to know Doom Emacs
 #+STARTUP: nofold
 
-This page is a WIP.
+Once you've installed Doom and launched it, the next step of your masochistic
+journey is to master it. This guide will walk you through many Doom-centric
+workflows you'll commonly find in a text editor (and beyond). It isn't
+exhaustive because I don't have enough lives to make it so.
+
+#+begin_quote
+If you feel like we've missed something, don't hesitate to let us know! You're
+welcome to [[https://discord.gg/qvGgnVx][join us on our Discord server]].
+#+end_quote
 
 * Table of Contents :TOC:
 - [[#day-1-in-doom-emacs][Day 1 in Doom Emacs]]
@@ -14,6 +22,7 @@ This page is a WIP.
   - [[#pipe-text-through-ex-commands-and-programs][Pipe text through ex commands and programs]]
   - [[#transposingswapping-text][Transposing/swapping text]]
 - [[#managing-your-projects][Managing your projects]]
+  - [[#reconfiguring-emacs-on-a-per-project-basis][Reconfiguring Emacs on a per-project basis]]
 - [[#search--replace][Search & replace]]
   - [[#project-wide-text-search][Project-wide text search]]
   - [[#search--replace-1][Search & replace]]
@@ -32,6 +41,8 @@ This page is a WIP.
 - [[#using-emacs-for][Using Emacs for...]]
   - [[#writing-fiction][Writing fiction]]
   - [[#writing-papers][Writing papers]]
+  - [[#note-keeping][Note-keeping]]
+  - [[#a-personal-organizer][A Personal Organizer]]
   - [[#composing-music][Composing music]]
   - [[#game-development][Game development]]
   - [[#web-development][Web development]]
@@ -48,6 +59,9 @@ This page is a WIP.
 ** TODO Pipe text through ex commands and programs
 ** TODO Transposing/swapping text
 * TODO Managing your projects
+** TODO Reconfiguring Emacs on a per-project basis
+*** TODO .dir-locals.el
+*** TODO editorconfig
 * TODO Search & replace
 ** TODO Project-wide text search
 ** TODO Search & replace
@@ -66,6 +80,8 @@ This page is a WIP.
 * TODO Using Emacs for...
 ** TODO Writing fiction
 ** TODO Writing papers
+** TODO Note-keeping
+** TODO A Personal Organizer
 ** TODO Composing music
 ** TODO Game development
 ** TODO Web development