Doc refactoring > README.md and installation.md

[pablos-here]

Hi,

This unit of work affects the main landing page. It is part of issue #672.

I want to submit it for review to check whether the writing style is in-line with the project. Please let me know if the style should be adjusted and how, any other feedback. The documentation is not ready yet (see the questions below). :)

We can decide whether to add more units of work to this PR or release it and I work on another chunk. Let me know what you prefer. Either workflow works for me.

Questions

1. Under manual installation, I'm unclear on the implications of Conda. What should we warn the user about?
2. I moved the Installation to its own page with intention of keeping the main page short and simple. I can easily put it back if it is preferred.

[sezanzeb]

This tool may also be helpful for those with repetitive strain issues.

Please no medical advice in our docs

[pablos-here]

This tool may also be helpful for those with repetitive strain issues.

Please no medical advice in our docs

Hi,

The intent was to convey that by remapping, you can address issues like Emacs pinky and the like. That's why I'm primarily using the solution.

If you feel strongly about it, we can simply strike it rather than re-word it.

I'm good either way.

Thx!

[sezanzeb]

"lag", I have never seen that word used in that context

[sezanzeb]

"Please note that distributions may provide more or less outdated packages."

[pablos-here]

"lag", I have never seen that word used in that context

In this context,it is a correct usage of lag.

I don't think we want to rewrite based on exposure to language.

"Please note that distributions may provide more or less outdated packages."

"more or less" is unfortunately incorrect because it is stating that a distribution may never have current packages. It is stating either more outdated or less outdated. I don't believe that's what we want to convey.

How about a slight modification as follows:

Please note that the distribution package may lag with the latest bug fixes.

[sezanzeb]

"more or less" is unfortunately incorrect because it is stating that a distribution may never have current packages.

Which is why my proposal says "distributions may provide".

I don't think we want to rewrite based on exposure to language.

I still don't like using lag like this.

Please use "Please note that distributions may provide more or less outdated packages."

[sezanzeb]

Suggested change

	<i><b>Warning:</b> the following will remove any existing <b>new</b>
	configurations.</i>
	<b>Warning:</b> the following commands will overwrite any new presets of
	version 2.0.0 or later.

[pablos-here]

If the user creates configurations 2.0.0, then says oops, I want to migrate my beta configs, the rm will wipe them out. I brought forward the rm from the original doc. Is the rm not necessary? Should I strike that step?

[sezanzeb]

Suggested change

	<i><b>Warning:</b> the following will remove any existing <b>new</b>
	configurations.</i>
	<b>Warning:</b> the following commands will remove any new presets of
	version 2.0.0 or later.

[sezanzeb]

Suggested change

	<a href="readme/installation.md">Installation</a></br>
	<a href="readme/installation.md">Installation</a> -

[pablos-here]

I was thinking that most users want to know how to install the software. This is why I put Installation on its own line. Perhaps later they'll come back for other activities such as Macros.

If you rather have Installation on the same line with everything else. I can do it but I wanted to explain my reasoning.

Let me know.

[sezanzeb]

If you rather have Installation on the same line with everything else

yes

[pablos-here]

Hi,

At your convenience, please have a look at this iteration.

A few notable (to me?) changes ...

On the installation.md, I went with the idea of removing the redundant warnings about lag. If it becomes a Support issue where people are fumbling around, we can tweak the doc.

On README.md, I centered the text (as it was) and created a two-column, bullet list of features. I also removed the repetitive strain text. Anyone who has it (like me), knows that a tool like input-remapper will alleviate the pain. :)

[sezanzeb]

There are also unaddressed old reviews from 4 days ago

[pablos-here]

There are also unaddressed old reviews from 4 days ago

AFAIK, those issues are awaiting responses from you.

[sezanzeb]

for example #673 (comment)...

[pablos-here]

for example #673 (comment)...

Near the end of my response, I say "let me know."

[pablos-here]

Hi Tobi,

It seems that you are very busy which is affecting the cadence of this PR. On my end, I've found a different key mapping solution that better matches my Use Cases.

As I see it, we have a couple of options. I can close the PR and either you hold onto the in-flight changes to complete or delete them.

To keep things tidy, one way or another, I'll close this PR within 24 hours from now.

Thanks!

[sezanzeb]

I don't know. I honestly can't see what is blocking you from resolving the three open review comments

[sezanzeb]

But yeah, you can keep it open and I'll add a label that someone else can continue this if wanted or something

[pablos-here]

I don't know. I honestly can't see what is blocking you from resolving the three open review comments

Hey Tobi,

You never answered my follow up questions nor asked for further clarification so I was blocked.

[sezanzeb]

What exactly is the open question that blocks you from doing this:

?

[pablos-here]

What exactly is the open question that blocks you from doing this:

?

Are you not able to see my responses?

Here's a screen scrape ...

[sezanzeb]

It says "Pending", you have to submit your review so that I can see your comments

[pablos-here]

It says "Pending", you have to submit your review so that I can see your comments

I had mentioned four days ago that I had written "let me know" but it clearly got missed. Now I know ... thx.

[pablos-here]

Hi @sezanzeb ,

As I mentioned, I'm no longer using input-remapper. You'll need to take over this PR or I can close it.

Have fun!