GitBook: [main] 97 pages modified

SUMMARY.md

@@ -50,9 +50,9 @@
         * [Block Parser Documentation](community/get-involved/learning-at-athens-academy-education/learn-in-public/clojure/athens-block-parser-documentation.md)
     * [File & verify issues](community/get-involved/learning-at-athens-academy-education/file-and-verify-issues.md)
     * [Review & submit pull requests](community/get-involved/learning-at-athens-academy-education/review-and-submit-pull-requests.md)
-    * [Contribute Documentation](community/get-involved/learning-at-athens-academy-education/contributing-documentation.md)
+    * [Improve the handbook & documentation](community/get-involved/learning-at-athens-academy-education/contributing-documentation.md)
     * [Improve Design](community/get-involved/learning-at-athens-academy-education/contributing-design.md)
-    * [Submit sample templates or databases](community/get-involved/learning-at-athens-academy-education/submit-templates-or-databases.md)
+    * [Share sample templates or databases](community/get-involved/learning-at-athens-academy-education/submit-templates-or-databases.md)
 
 ## COMPANY
 

community/athens-guide/README.md

@@ -1,6 +1,2 @@
----
-description: The Guide Book
----
-
 # Athens User Guide
 

community/athens-guide/getting-started/installation-guide.md

@@ -15,7 +15,7 @@ When using the desktop app, Athens stores your knowledge graph in a local folder
 
 If you need to edit your knowledge graph from multiple machines or on different networks, you have two choices:
 
-* Use a file system tool like Dropbox or OneDrive. While Athens warns you about updated blocks coming from these syncing tools, you should take care not to edit the same database from multiple machines at the same time.
+* Use a file synchronization tool like Dropbox or OneDrive. While Athens warns you about updated blocks coming from these syncing tools, you should take care not to edit the same database from multiple machines at the same time.
 * Run the [Athens backend](https://github.com/athensresearch/athens-backend) on a system, like a virtual private server \(VPS\) or [Heroku deployment](https://github.com/athensresearch/athens-backend#heroku) that you can access from every machine or network.
 
 ## Import a Preexisting Database

community/get-involved/contributing.md

@@ -24,8 +24,9 @@ We're always looking to bring new people and new ideas into Athens. There's plen
 
 ### Go deeper
 
-* [Share your workflows](learning-at-athens-academy-education/share-your-experiences.md) to help others become Athens gurus.
 * [Connect with Athens](learning-at-athens-academy-education/connect-on-social-media.md) on social media.
+* Ask and answer questions 
+* [Share your workflows](learning-at-athens-academy-education/share-your-experiences.md) to help others become Athens gurus.
 * [Report bugs](learning-at-athens-academy-education/file-and-verify-issues.md) when something is broken.
 * [Request new features](learning-at-athens-academy-education/request-new-features.md) to add functionality.
 * [Improve this handbook](learning-at-athens-academy-education/contributing-documentation.md) to make Athens more transparent and approachable.

community/get-involved/learning-at-athens-academy-education/ask-and-answer-questions.md

@@ -1,2 +1,31 @@
 # Ask & answer questions
 
+The Athens community is all about learning in public, and in order to learn, we need people who are willing to learn _and_ we need teachers! Asking questions, or giving helpful answers in response, helps grow the community's collective understanding.
+
+Feel free to ask & answer questions on any pillar of the Athens community. 
+
+* **Discord:** Most application-specific questions/answers should go in the `#help` and `#questions` channels on our [Discord server](https://discord.gg/as9h8yHNfD).
+* **GitHub**: The best place is the [Discussions forum](https://github.com/athensresearch/athens/discussions).
+* **Twitter**: Find us on Twitter [@AthensResearch](https://twitter.com/AthensResearch).
+
+### Ask
+
+There are a few ways to make your question as valuable to the community as possible:
+
+* Search the [Athens repository on GitHub](https://github.com/athensresearch/athens), including the [Discussions](https://github.com/athensresearch/athens/discussions) and [issues](https://github.com/athensresearch/athens/issues), to see if someone asked and answered the question before you.
+* If you're on the [Discord server](https://discord.gg/as9h8yHNfD), search there as well.
+* Describe your issue or concern in as much detail as possible to reduce back-and-forth.
+* Thank the person\(s\) who end up answering you!
+
+### Answer
+
+Here are a few things to keep in mind when answering questions:
+
+* Follow our [Code of Conduct](../code-of-conduct.md) at all times.
+* You always have the authority to answer a question! There is no hierarchy to the Athens community and no "owner" of a certain type of question.
+* Maintain a positive and empathetic tone when answering questions. All of us are always learning.
+* Link to a page in the handbook or a GitHub issue/PR/discussion thread as part of your answer if there is documentation or further context available.
+* If you can answer part of a question but think there should be follow-up from someone else who might know more, check out the profiles of the [core team](../../../company/org-chart/core-team/) and loop in the most relevant person.
+
+If you've answered the same question a few times, or see others do the same, it might be time for an [improvement to the handbook](contributing-documentation.md).
+

community/get-involved/learning-at-athens-academy-education/contributing-documentation.md

@@ -5,43 +5,36 @@ description: >-
   fixes and improvements across the board.
 ---
 
-# Contribute Documentation
+# Improve the handbook & documentation
 
-Athens Research uses the [`athensresearch/handbook` repository](https://github.com/athensresearch/handbook) on GitHub as the source of truth for all its documentation and information on using Athens, contributing to development, governance, and more. The files in this repository are published to the [Athens Handbook](https://athensresearch.gitbook.io/handbook/) for reading.
+Athens Research uses this handbook as the source of truth for all its documentation and information on using Athens, contributing to development, governance, and more.
 
-We publish the Markdown files in this repository using GitBook via a two-way synchronization process. When a member of the Athens community makes an edit on GitBook, it's synchronized back to this repository.
+The files in the  [`athensresearch/handbook` repository](https://github.com/athensresearch/handbook) are published to the [Athens Handbook](https://athensresearch.gitbook.io/handbook/) with GitBook.
+
+### Contributing to the handbook
 
 All contributors, and contributions of any type, are welcome. A community of many voices and perspectives produces the most inclusive and accurate documentation.
 
-If you're not sure where to start, check out the [Documentation project](https://github.com/athensresearch/athens/projects/17) on GitHub, which is where the Athens community discusses and organizes, coordinates, and claims tasks related to documentation.
+Learn about current priorities and TODOs by checking out the [Handbook project](https://github.com/athensresearch/handbook/projects/3) on GitHub, which is where the Athens community discusses and organizes, coordinates, and claims tasks related to the handbook.
 
-There are two ways to suggest or make changes to the handbook:
+If you want to make the handbook better, but don't want to work on the handbook itself, [filing issues](file-and-verify-issues.md) for missing our outdated information is incredibly helpful to the handbook team.
 
-1. [**GitHub**](contributing-documentation.md#contribute-with-github): Edit Markdown files in a new branch, then submit a pull request for review from members of the Athens core team or community.
-2. [**GitBook**](contributing-documentation.md#contribute-with-gitbook): If you're less comfortable with using GitHub or editing Markdown, use rich-text, drag-and-drop editing tools to edit the handbook directly.
+#### Handbook team
+
+We currently have a small team of contributors who 
 
 ### Language and tone
 
-Our handbook should assume zero prior knowledge. Be descriptive without the unnecessary use of jargon. If jargon is unavoidable, link to definitions or educational pages that describe the jargon/concepts.
+Our handbook should assume zero prior knowledge. Be descriptive without the unnecessary use of jargon. If jargon is unavoidable, link to our glossary or external educational pages that describe the jargon/concepts.
 
-### Handbook structure
+### Editing the handbook
 
-* **Use Athens**: Product documentation for the [Athens](https://github.com/athensresearch/athens) desktop or [web](https://github.com/athensresearch/athens-backend) \(self-hosted\) application.
-  * Stored in `/for-users/`. 
-* **Build Athens**: How-to guides on how to contributing to 
-  * Stored in `/contributing-1/`.
-* **Athens Team Operations**: Governance information for Athens Research as a company and community.
-  * Stored in `/company/`.
-* **Develop Athens**: Developer documentation for Athens.
-  * Stored in `/development/`.
-* **School of Athens**: Information about ClojureFam, our cohort-based learning program for teaching developers about Clojure, the language Athens is written in, and other educational efforts.
-  * Stored in `/school-of-athens/`.
-* **Frequently Asked Questions**: Answers to common questions that users might have about Athens Research, Athens, ClojureFam, or any other part of the Athens ecosystem.
-  * Stored in `/frequently-asked-questions-faq/`.
-* **Glossary**: A dictionary of Athens-specific terminology and industry jargon.
-  * Stored at `/glossary.md`.
+There are two ways to make changes to the handbook:
+
+1. [**GitHub**](contributing-documentation.md#contribute-with-github): Edit Markdown files in a new branch, then submit a pull request for review from members of the Athens core team or community.
+2. [**GitBook**](contributing-documentation.md#contribute-with-gitbook): If you're less comfortable with using GitHub or editing Markdown, use rich-text, drag-and-drop editing tools to edit the handbook directly.
 
-### Contribute with GitHub
+#### GitHub
 
 Contributing to documentation with GitHub requires a few things:
 
@@ -68,16 +61,21 @@ Click **Create pull request** to create the PR. A member of the Athens team will
 
 #### Images
 
-There are two ways to attach images to your documentation contributions.
+The best way to attach images to your handbook contributions is to upload image assets to GitHub.
+
+Drag-and-drop your image into the textarea at the bottom of any issue or PR.
+
+1. ![Uploading a file to GitHub](https://user-images.githubusercontent.com/1153921/118381822-e6b74800-b5a3-11eb-9c0f-42850d33093f.gif)
 
-1. Add the image file into the `.gitbook/assets` folder in this handbook repository alongside your changes to text. Reference the image starting from the root of the repository `/`, followed by `.gitbook/assets/`: `![alt text](/.gitbook/assets/import.png)`.
-2. Upload the image directly to GitHub. Drag-and-drop your image into the textarea at the bottom of any issue or PR.
+GitHub returns an `<img>` element with the file uploaded to their content delivery network \(CDN\):
 
-   ![Uploading a file to GitHub](https://user-images.githubusercontent.com/1153921/118381822-e6b74800-b5a3-11eb-9c0f-42850d33093f.gif)
+```text
+<img width="1440" alt="Creating a new PR with a recent push" src="https://user-images.githubusercontent.com/1153921/118381383-36dfdb80-b59f-11eb-93b5-f6efd6aa26d1.png">
+```
 
-   GitHub returns an `<img>` element with the file uploaded to their content delivery network \(CDN\): `<img width="1440" alt="Creating a new PR with a recent push" src="https://user-images.githubusercontent.com/1153921/118381383-36dfdb80-b59f-11eb-93b5-f6efd6aa26d1.png">`. Add this string to your document to embed the image.
+Add this string to your document to embed the image.
 
-### Contribute with GitBook
+#### GitBook
 
 Contributing to documentation with GitBook requires an invitation to the app.
 
@@ -92,7 +90,25 @@ To make changes directly:
 * Open a file and make your changes using the built-in editor.
 * Hover over the popup in the bottom-left corner. Add a description of your changes in the text area and click **Save**.
 * At this point, other writers and administrators can see your edits. Send a message on the `#documentation` channel on [Discord](https://discord.com/invite/as9h8yHNfD) to encourage others to respond and provide feedback.
-* Once you feel comfortable merging, click the **Merge** button. GitBook immediately publishes your changes and commits
+* Once you feel comfortable merging, click the **Merge** button. GitBook immediately publishes your changes and commits them back into the handbook repository.
 
-  them back into the handbook repository.
+### Handbook structure
+
+* **Welcome**
+  * Stored in the main `README.md`.
+* **About us**
+  * Information about Athens Research, what's new, and our vision.
+  * Stored in `/about-us/`.
+* **Athens User Guide**
+  * Product documentation for the [Athens](https://github.com/athensresearch/athens) desktop or [web](https://github.com/athensresearch/athens-backend) \(self-hosted\) application.
+  * Stored in `/community/athens-guide/`. 
+* **Athens Community Guide**: 
+  * Guides on the many ways of contributing to the Athens community and ecosystem.
+  * Stored in `/community/get-involved/`.
+* **Company**
+  * Information for Athens Research as a company, including its core team, contributors, and operations.
+  * Stored in `/company/`.
+* **Help**
+  * Contact information, answers to common questions, and a glossary of Athens-specific terminology and industry jargon.
+  * Stored in `/help/`.
 

community/get-involved/learning-at-athens-academy-education/share-your-experiences.md

@@ -1,2 +1,22 @@
 # Share your workflow
 
+One of the challenges in using knowledge graph tools like Athens is understanding how to get started and how to most effectively organize your thoughts. Even with powerful features like [Bidirectional Links](../../athens-guide/feature-list/bidirectional-links.md) and [Block References](../../athens-guide/feature-list/block-references.md), which effectively eliminate the need to waste time organizing your notes into a hierarchical file-folder structure, we tend to constantly search for the "best" way to use Athens.
+
+We tend to ask questions like:
+
+* Should I take notes in the daily pages, or on per-subject pages?
+* Should I make a new block for this thought, or an entirely new page?
+* When should I use the `[[link]]` syntax as opposed to `#[[link]]` and how does that affect my workflow?
+* _What if I don't get it right the first time?_
+
+You can help eliminate this fear by sharing your workflow. Here's a few suggestions on how to do just that:
+
+* **Write a blog post**: Give us a guided tour of your knowledge graph, along with strategies on how and why you organize your thoughts. Here's some good examples using Athens and similar tools:
+  * [Multiplayer Learning in Public with Roam Research](https://roamresearch.com/#/app/Symposium/page/4i6PyCSfi)
+  * 
+* **Record a video**: Use [Loom](https://loom.com), or any desktop screen recording tool, and a microphone to record yourself walking through how you use Athens to take notes and organize your thought. Again, some good examples:
+  * [How we're using @RoamResearch to build collective learning in the @code423n4 DAO](https://www.loom.com/share/7316d46335e1480eb548b4a3c1e2de86)
+* **Upload your templates or database:** If you have a "template" that you copy-paste into your daily page, or an [entire database you're willing to share](submit-templates-or-databases.md), we'd love to explore. 
+
+
+

community/get-involved/learning-at-athens-academy-education/submit-templates-or-databases.md

@@ -1,2 +1,43 @@
-# Submit sample templates or databases
+# Share sample templates or databases
+
+We're always looking to build out a library of templates and databases that any Athens user can download and start applying to their knowledge graph. We don't currently have a centralized "library" of these assets at this point. In fact, we're mostly focused on getting the community to share these workflows so that we can compile them into a centralized location.
+
+### Templates
+
+Templates are placeholder blocks that you paste into a new page to provide some preconfigured structure. For example, if you use Athens for a daily journal, you might start with a template like this:
+
+```text
+- **How many hours of sleep did I get?**
+  - 
+- **How am I feeling this morning?**
+  - 
+- **What's the one thing I need to get done today to move forward?**
+  -
+```
+
+Here's how to share a template:
+
+* Paste your template directly into the `#workflow` channel on our [Discord server](https://discord.gg/as9h8yHNfD).
+* Create a [GitHub Gist](https://gist.github.com/) and paste your template into it.
+  * Share your Gist on the `#workflow` channel on our [Discord server](https://discord.gg/as9h8yHNfD).
+  * Tweet us at [@athensresearch](https://mobile.twitter.com/AthensResearch).
+
+### Databases
+
+Sample databases are one way that newer Athens users can explore [workflows](share-your-experiences.md) and learn organizational strategies from those who are more experienced with personal knowledegebase management \(PKM\) tools. 
+
+We have a [Google Drive folder](https://drive.google.com/drive/folders/1E8z-s33PfzNCGxEsZNQlB5niVq9bKQg0?usp=sharing) that anyone can upload an sample database to. We hope that, in time, we'll have dozens of sample databases to explore and learn from.
+
+Use the following process to upload a sample database:
+
+* Create a copy of your database \(the `index.transit` file\).
+* Rename your database from `index.transit` to something else that describes your use case or workflow. For example, `book-club.transit`.
+* Upload your database to the [Google Drive folder](https://drive.google.com/drive/folders/1E8z-s33PfzNCGxEsZNQlB5niVq9bKQg0?usp=sharing).
+* Let us know about it!
+  * Share the link to your database in the `#workflows` channel on our [Discord server](https://discord.gg/as9h8yHNfD).
+  * Tweet us at [@athensresearch](https://mobile.twitter.com/AthensResearch).
+
+{% hint style="warning" %}
+Don't upload a database with personal information that you don't want shared!
+{% endhint %}