Improving documentation.

[useredsa]

Solves #24.

[useredsa]

Any comments?

[alexherbo2]

@useredsa I do not have much time to review.

[alexherbo2]

@useredsa Looks good. I haven’t finished the review.

[alexherbo2]

@useredsa Tell me when it’s ready.

I added/renamed some commands in the meantime. Maybe you want to update.

[useredsa]

@useredsa Tell me when it’s ready.

I added/renamed some commands in the meantime. Maybe you want to update.

It is ready right now.

Note that I moved ide and cd behaviour to recipes.

[alexherbo2]

@useredsa Would you be ok to present the new features in a post?

I think something is missing in the project, is how the magical works, what is the core of connect.kak and how we build things upon these blocks.

Also about conventions, why connect commands start with :.

[useredsa]

@useredsa Would you be ok to present the new features in a post?

Instead of in the project repository or in addition? I think the documentation for the project shall be with the project and a separate post can be written in the forum commenting the additions.

I think something is missing in the project, is how the magical works, what is the core of connect.kak and how we build things upon these blocks.

Yes. My intention is that this information should be in the integration file. Right now it's pretty short, but it could be expanded in future commits, don't you think?

Also about conventions, why connect commands start with :.

Hmm... I was using faq.md to include this kind of things. It is true that instead of frenquently asked questions it's more a file about conventions/design decisions. I vote for changing the name.

[alexherbo2]

Yep in Discuss or reddit.

[useredsa]

Last minute changes:

diff --git a/README.md b/README.md
index 6598834..e7a2a0d 100644
--- a/README.md
+++ b/README.md
@@ -217,13 +217,13 @@ PS1='$(~/.local/share/kak/connect/prompt) $ '
 - [Commands]
 - [Aliases]
 - [Modules]
-- [FAQ]
+- [Extra documentation for users][user-extra-documentation]
 - [Recipes]
 - [Integration with other tools][integration]

 [Commands]: rc/connect/commands
 [Aliases]: rc/connect/aliases
 [Modules]: rc/modules
-[faq]: docs/faq.md
+[user-extra-documentation]: docs/user-extra-documentation.md
 [recipes]: docs/recipes.md
 [integration]: docs/integration.md
diff --git a/docs/faq.md b/docs/user-extra-documentation.md
similarity index 74%
rename from docs/faq.md
rename to docs/user-extra-documentation.md
index cd6bc36..9348726 100644
--- a/docs/faq.md
+++ b/docs/user-extra-documentation.md
@@ -1,6 +1,8 @@
-# FAQ
+# Extra documentation for users

-## What’s the difference between `>` and `$`?
+## FAQ
+
+### What’s the difference between `>` and `$`?

 `>` or `connect-terminal` runs its argument
 (which by default is your shell)
@@ -11,7 +13,7 @@ Some programs must be run inside a terminal,
 while others spawn their own graphical window.
 Use `>` for the first type and `$` for the second.

-## What’s the purpose of `&` or `connect-detach`?
+### What’s the purpose of `&` or `connect-detach`?

 `connect-detach` detaches (closes) the current client
 (leaving you in a terminal if you launched Kakoune there) and
@@ -24,7 +26,7 @@ you didn’t start it in daemon mode.

 **Note 2**: The implementation uses Kakoune’s `quit!` command instead of `quit`.

-## What is `kak-shell`?
+### What is `kak-shell`?

 `kak-shell` is inspired by [nix-shell].

@@ -52,7 +54,11 @@ For example, you could run `kak-shell tig` to run [tig] connected to an arbitrar
 [tig]: https://github.com/jonas/tig
 [nix-shell]: https://nixos.org/nix/manual#sec-nix-shell

-## What’s the difference between [commands] and [modules]?
+---
+
+## Conventions and design decisions
+
+### What’s the difference between [commands] and [modules]?

 The term module is used for small program integrations for Kakoune
 (which are implemented as Kakoune’s modules).
@@ -61,3 +67,11 @@ The term command is used for small binaries that can be used by a connected appl
 [commands]: ../rc/connect/commands
 [modules]:  ../rc/modules

+### Why do all [commands] start with a colon (`:`)?
+
+The colon is the key used to access the prompt menu inside Kakoune.
+Because the commands usually resemble Kakoune commands,
+prepending them with a colon is a good way to reuse our muscle memory,
+and it makes it very simple to differentiate them from traditional commands
+(think of `pwd` versus `:pwd`).
+

[useredsa]

Yep in Discuss or reddit.

If you want me to post it I prefer to do it in discuss, since I don't use reddit. I'm fine if you prefer to post it yourself.

[alexherbo2]

I’m not good for explaining things. xd

[useredsa]

I’m not good for explaining things. xd

:open_mouth: :facepalm: ...