Documentation improvement ideas

[zrzka]

Still reviewing (WIP) and will gather more ideas by editing this first comment. Don't take it as criticism, I'm just trying to think as a first time user / beginner and follow the standard library way of documentation.

docs.rs

• crossterm main page refers to other crates, but the link points to crates.io (https://crates.io/crates/crossterm_style), not to docs.rs (https://docs.rs/crossterm_style/latest/crossterm_style/), I'd expect that when I'm reading documentation that I'll be redirected to other crate documentation as well
• Punctuation (some sentences do end with the ., some don't)
• Inconsistent usage of examples
  • Sentences like Check /examples/ in the library for more specific examples. or Please checkout the example folder in the repository. don't help much
  • I'd expect examples in the documentation (or at least links to the GitHub examples folder)
  • I'd expect more sophisticated examples in the GH examples folder
  • Some examples are in the # Examples section, some aren't
• Inconsistent parameters handling
  • For example - scroll_down - param is count and docs contain Scroll n lines down in the current terminal. (n vs count)
  • I'd remove some parameter docs, like standard library, when it's really obvious what it does

README.md

• Some links (like Crossterm Type) don't work

[TimonPost]

Thanks for your findings, I see it as feedback, it is very important how a starter sees this project. I have always tried to make readme, examples, documentation as clear as possible, so if there are more improvements to be done, I'd like to hear it.

I'd expect that when I'm reading the documentation that I'll be redirected to other crate documentation as well

But what if you read it on cargo, should it then show docs.rs? Or what if you read it on GitHub should it then show docs?

Sentences like Check /examples/ in the library for more specific examples. or Please check out the example folder in the repository. don't help much

I don't see what is unclear about Please checkout the example folder in the repository. The other can be changed since it might not be clear what's being said.

I'd expect examples in the documentation (or at least links to the GitHub examples folder)

I once had a lot of examples in all documentation strings, but this is a pain to maintain and difficult to keep up to date. That's why I decided to move all examples and demos to github folder, which can be compiled and rand.

I'd expect more sophisticated examples in the GH examples folder
Do you have any examples on that, I have an example for each functionality of crossterm it is very detailed. If you want to see how it integrates into a larger envoirment I suggest you to check /examples/program_examples.

For example - scroll_down - param is count and docs contain Scroll n lines down in the current terminal. (n vs count)

Yea that could be scroll_row_count or something similar.

[zrzka]

But what if you read it on cargo, should it then show docs.rs? Or what if you read it on GitHub should it then show docs?

I don't understand what do you mean with read it on GitHub. I probably wasn't clear enough in this case. I meant just these lines.

I don't see what is unclear about Please checkout the example folder in the repository. The other can be changed since it might not be clear what's being said.

&

I once had a lot of examples in all documentation strings, but this is a pain to maintain and difficult to keep up to date. That's why I decided to move all examples and demos to github folder, which can be compiled and rand.

It's clear, but it doesn't help much - I mean, it's okay that you do not want more examples in the docs, but at least there can be a link to the GH folder / specific example. Which, at least, helps in a way that I'm not forced to search for it and I can just click.

[TimonPost]

Right, I see your point. Links can be added, or if the lib is more stable, the examples can be added back. My second problem with the examples in the documentation is that for a function like: size you would have:

let terminal = Terminal::new();
terminal::size();

It is kind of obvious how to call this function. There is not much more magic to it then to create an instance and call the function. Examples would be a bit repetitive.

[TimonPost]

I am closing this issue. I think you have improved most of those issues in the clean up PR's

[zrzka]

Nope, I didn't. Still lot work to do here ...

[zrzka]

To make it more clear, I made #265. With the documentation improvement, I mean phase 1 & 2 from this issue. Anyway, because I made the #265, I'm closing this one in favor of it.