adds documentation guidelines

10 Notes/Codex Documentation Setup.md

@@ -0,0 +1,22 @@
+Let' take a look at the drawing below:
+
+![[HackMD_GitHub_Obsidian-1.svg]]
+
+
+GitHub is our source of truth. You connect to the team by cloning the repo on your machine. Think of it as a database. Of course you can use SQL queries to edit the database directly, but often you will use a more convenient system to input your data to the database. Obsidian is such a more convenient system. Now when you modify or add a document via Obsidian, these changes stay local (or private). To have them available to others, you need to commit your changes to the underlying git repository and push the changes to GitHub (usually via a separate PR).
+
+Your local drive is not the only way things can end up in our documentation repository. The other valid way is [HackMd](https://hackmd.io/):
+
+![[HackMD_GitHub_Obsidian-2.svg]]
+*USER 1* and *USER 2*, can pull the content to HackMD, and push the changes back, without using Obsidian at all (we will see later why we do recommend to still use Obsidian even when using in HackMD). Also, the user may be tempted to just use HackMd, without using either GitHub or Obsidian and just make sure that just add the content to the *Codex Storage* workspace on HackMd - *also not recommended*.
+
+![[CodexDocumentationSetup-20250807072740.png]]
+
+Thus, to keep things manageable, we distinguish two workflows:
+
+1. [[GitHub-Obsidian Workflow]]
+2. [[HackMD-GitHub-Obsidian Workflow]]
+
+[[GitHub-Obsidian Workflow]] is the default workflow when you do not have to extensively collaborate on the document or if the comments on the created PR are sufficient to effectively communicate and decide on the final content. The [[HackMD-GitHub-Obsidian Workflow]] is more complex, and thus should only be used when the document is a collaborative effort and you expect lots comments and iteration before converging to something more stable.
+
+Above, we mention that using HackMD alone is not recommend. Why? The reason is very simple. When the number of documents is low, and they are not interconnected, it is indeed tempting to make one's live easier and just keep lots of documents in HackMD. What if HackMD becomes unavailable? Or if we decide to use a different tool to collaborate on the content. Moving lots of files from HackMD will be a pain. Finally, it requires much more discipline and manual effort to keep the documents organised on HackMD via folders, bookmarks, and tags. Thus, please only use the two workflows listed above. 

10 Notes/GitHub-Obsidian Workflow.md

@@ -0,0 +1,10 @@
+This is the simplest workflow. Ideal if you do not need to collaborate with many other contributors on the document or when using the GitHub PR comments is sufficient.
+
+1. Create the document in Obsidian.
+2. Create a branch and a (draft) PR.
+3. Get the approval(s).
+4. Merge to `main`.
+
+That's it from the team collaboration perspective.
+
+To sync the vault on your computer with your other devices see also: [[Syncing Obsidian Vault with your other devices]].

10 Notes/HackMD-GitHub-Obsidian Workflow.md

@@ -0,0 +1,18 @@
+This workflow is slightly more complex. Not only because you need to pull/push content from/to GitHub, but because it is easy to create a mess.
+
+The workflow is the following:
+
+1. Author the document in Obsidian.
+2. Create a branch and a (draft) PR.
+3. Pull the content in HackMd in the *Codex Storage* workspace.
+   *Consider using a separate folder named after your branch.*
+4. Invite collaborators.
+5. Collaborate, comment, and modify the document content. Take special care for images and similar media files that you want to embed in the document (links are *ok* sparingly, but it is always better to have a local copy kept on GitHub). If you do it via HackMd, you need to take care later that this content is copied to GitHub and properly linked in Obsidian (in Obsidian all the assets are kept in the `90 Extras/92 Assets` directory - this is where your non-markdown media files need to end up). If you do not need to collaborate on the media content or when you can just share them via some other channel, it is usually easier to add this content via Obsidian and then pull the changes to HackMD (although the media will not render in HackMD in such a case, unless you use direct links to that content on GitHub - temporarily fine, but not recommended in the final document). Obsidian is very convenient to work with media content in your markdown, so please take advantage of it.
+6. After you reach consensus, push the final version of the document to your PR branch.
+7. Check the content in Obsidian.
+8. Get the PR approval(s).
+9. Merge `main`.
+10. Consider deleting the merged content and the "branch" folder from HackMD.
+    _HackMD does not seem to have any convenient way to export comments, so if you need to preserve the conversation, I would consider creating a separate document and copy the conversation or its summary there. Keeping the document hanging in HackMD sooner or later will result in a mass. Let's build a good habit: **all documents in GitHub**._
+
+Consider checking our [[Using Codex Obsidian Vault Video Tutorials]]. There is one about using HackMD, GitHub, and Obsidian together.

10 Notes/Ignored Obsidian Vault files.md

@@ -0,0 +1,10 @@
+Not everything from the vault should go to the repository. For instance: your workspace settings should stay private as they change every time you open a new file. Similarly, you `10 Notes/Inbox` file - which is similar to a scratch buffer - should stay private as well. Also, currently, the calendar entries that are stored in the `00 Planner/` folder are currently considered private.
+
+If you need to have some specific file ignored, you may decide to add your own entry to `.github` in a section that starts with a comment, e.g.
+
+
+```
+# John Doe ignore list
+```
+
+or something similar. Try to be specific and consider placing the content you need to have ignored under the `10 Notes` folder temporarily, e.g. `10 Notes/JhonDoe` and then ignore that whole folder in `.gitignore`. It is wise to consider keeping your private stuff in a private vault and keep the Codex vault more suitable for the team content.

10 Notes/Short Introduction to Obsidian.md

@@ -1,7 +1,5 @@
 Here a short intro to [Obsidian](https://obsidian.md) and *Personal Knowledge Management Systems*. 
 
-We also have some video tutorials: see [[Using Codex Obsidian Vault Video Tutorials]].
-
 I currently, document some of the Codex/BitTorrent stuff in the vault you already can use to see how does it feel for you. The vault is available on GitHub: [https://github.com/codex-storage/bittorrent-codex-docs](https://github.com/codex-storage/bittorrent-codex-docs). You can just clone the rero, and open the cloned folder in Obsidian. That's it. This is you local copy - anything you do is only visible to you. GitHub is used for a more controlled syncing. Normally, when you work on your own content, you will put your vault on some shared network drive (end-to-end encrypted of course! :yum:  ), and then you can conveniently open it on any other device. Syncing is done by the network drive, Obsidian has nothing to do with it in this case. You content keeps the same structure (including folders) as you see it in your local (shared) folder - thus, everything is transparent and extremely portable. Myself, I have a paid subscription to Obsidian Sync service (not that I really need it, but I wanted to try it and to support the Obsidian team a bit). It costs me $96,00 per year:
 
 ![[Pasted image 20250513024925.png]]

README.md

@@ -1,18 +1,19 @@
-## Codex Documentation Vault
+This is our documentation repository. All documents that need to be recorded and available to the whole team have to end up here. This repository is also an [Obsidian](https://obsidian.md) vault. As much as you can jump directly to a specific Markdown file, it is strongly advised that you use Obsidian to update existing docs and to create and link new ones. Otherwise you may break the linking and cause problems to other users of this repo.
 
-This is our documentation. An [Obsidian](https://obsidian.md) vault containing
-all Codex-related docs.
+### Quick start
 
-Some featured documents:
+First, clone this repo to a local directory on your computer (e.g. `~/Documents/obsidian/codex):
 
-- [[Codex Encryption Basis]]
-- [[How to build Codex on Ubuntu 24 (VM)]]
-- [[Compilation error when using `auto` types and Questionable]]
+```bash
+git clone git@github.com:codex-storage/codex-docs-obsidian.git
+```
 
-### Obsidian
+Then install [Obsidian App](https://obsidian.md/download) (use the best method suitable for you OS).
 
-This repository is a complete [Obsidian](https://obsidian.md) vault. You can open it on your computer in the [Obsidian App](https://obsidian.md/download) and have a searchable Codex documentation vault under your full control. Comparing to bloated [Notion](https://www.notion.so), which is a great tool for procrastination rather than a tool for capturing knowledge, Obsidian let's you capture the knowledge quickly and with excellent overview of how different topic connect to each other. And in the end - all are just Markdown files.
+Finally, open the cloned folder (a vault) in Obsidian.
 
-The vault includes the `.obsidian` folder, but does not include publishing settings, and workspace configuration as those are personal and change every time you open the vault. If you want to have the full control over your Obsidian look and full, your own [[Hot-Keys|hot-keys]], [[Installed plugins|plugins]], etc, your can delete `.obsidian` or replace it with your own.
+Now you have a searchable Codex documentation vault under your full control. Everything you do in Obsidian remains private as long as you do not commit and push your changes to GitHub. Our `.gitignore` keeps some of the vault file ignored, meaning they will stay only visible to your Obsidian installation. For instance, the publishing settings and the workspace configuration (kept in the `.obsidian` folder) are excluded from GitHub syncing, as those are personal and change every time you open the vault. You can read more about what is ignored in [[Ignored Obsidian Vault files]].
 
-To learn more about Obsidian and *Knowledge Management Systems*, please also check [[Short Introduction to Obsidian]].
+> To get some background about Obsidian and *Knowledge Management Systems*, please check [[Short Introduction to Obsidian]]. We also have some video tutorials: see [[Using Codex Obsidian Vault Video Tutorials]].
+
+Now, when you have everything up and running, learn a bit more about our documentation setup and how to take full advantage of it. See [[Codex Documentation Setup]] in - of course - Obsidian.