search

zee-editor / zee

A modern text editor for the terminal written in Rust
Apache License 2.0
1.48k stars 42 forks source link

[Feature Request] More Detailed Documentation #39

Open kevinmatthes opened 2 years ago

kevinmatthes commented 2 years ago

Hello!

Thank you for this software! At the moment, I am trying to get started with zee but I often need to work myself through the respective implementation of a certain feature in order to get an idea of how I can interact with it. I would, hence, like to request an extension of the present documentation for future releases.

cargo doc --open gives me an overview of how the code organised but the provided information should rather be enriched with further explanations and some examples in order to provide an intuitive introduction to zee. This would also help other users new to this editor to get started very easily. Many Rust projects provide their documentation that way.

I tried to take a look at the wiki of this repository but it seem to do not be present and / or working, I was always redirected to the main page. The wiki would be another option to collect especially community driven suggestions on how to work with zee most effectively.

Finally, there is an even more detailed way to document the application: an mdbook. Large projects like just deploy their documentations with this feature.

Expanding the README is not always the best idea which is why I would recommend this option. One risks to reduce the maintainability of the README.

Which options would you prefer?

mcobzarenco commented 2 years ago

Thanks for the issue -- yes, indeed, documentation is super important and extending the README is not always the best thing. I actually bought zee.rs domain and set up github pages and Docusaurus -- you can see it's just the default Docusaurus page deployed. I chose Docusaurus over mdbook purely for aesthetics -- you get to write markdown in both. I am not opposed to revisiting this decision. Unfortunately I have not found the time to write docs yet (or for that matter implement a suite of crucial features in zee that would enable me to use it daily, such as smart indentation and lsp support).

I will prioritise writing a first pass of the docs, that would make it easier for others to contribute too.