Add installation page under tutorials

[sbis04]

I have added the Installation page under the Tutorials section to make it easier for users to find how they can install the required build tools on their system and smoothly get started with the tutorials.

The updated version of the screenshot is in a comment below.

[sbis04]

Tag #891

[Rohitesh-Kumar-Jain]

Seems good to me, great work.

[proudofsimin]

First of all, thank you so much for your effort, but documenting how to install/ update Node.js is not our responsibilities. You could simply add a note of prerequisite telling users to make sure they have installed Node.js 12.0 or greater and provide the link of installation document from Node.js if they haven't. We shall focus our documentation on Wechaty itself.

Since you've already written this part down, it's ok to leave it here. However, please add instructions to direct users to Install Wechaty if they have Node.js ready. This is to prevent that they skip the whole section when they see Install Node.js and think they've already done this part.

[sbis04]

Yes, I know at a first glance it might seem that this Installation section is not that important for it to have a separate page. For the main installation of Node.js I have just provided the links to the respective platform (as they can follow the official guide), but as Wechaty requires Node.js version greater than 12 so I have provided a command how they can check that.

So if their version is below 12 then they have to update Node.js to the latest version. And if you try searching something like "How to install node.js" you will only get third-party links as Node.js docs doesn't provide any official guide for updating (so most users will get overwhelmed by this). This is why this section is important.

If you check the Tutorials section of the Django docs you will find a similar thing (Quick install guide).

This page is required because I think it gives the users a good understanding of what the minimum requirements are for running any Wechaty bot on a single page and simplifies the process of installation.

Also, I think it's not required to provide instructions to direct users to Install Wechaty because it is a quite short page and users can see the contents of the page in the right panel:

And one more suggestion, previously we been including the installation links on the bot tutorial pages (for example the Getting Started section of Vorpal tutorial). But as we are now having the Installation page separately, so we don't need to add it again there and just direct the users to that page if they don't have them installed. And, just provide a command for checking if their Node.js version is above 12.

I just noticed, the Django docs have a similar format 😅 :

@proudofsimin let me know what do you think about it, or if you have any other suggestions.

[proudofsimin]

btw, don't is better than do not. See Contractions.

[sbis04]

I have changed it to don't.

[proudofsimin]

Hi @sbis04,

I understand that you are being very thoughtful for our users and it is really great especially when you are doing tutorials. I'm not blaming on you. I just afraid that you did too much work! It is actually Node.js who needs to provide the guides for update, and I'm really glad that you have thought of it and document for our users. This kind of situation actually happens a lot so people sometimes compromised and if it's not long, yes it's more user-friendly to include the. pre-installation part in.
Here is an example that originally I expected this part (prerequisite) to be. Example

[Rohitesh-Kumar-Jain]

Hi @sbis04,

I understand that you are being very thoughtful for our users and it is really great especially when you are doing tutorials. I'm not blaming on you. I just afraid that you did too much work! It is actually Node.js who needs to provide the guides for update, and I'm really glad that you have thought of it and document for our users. This kind of situation actually happens a lot so people sometimes compromised and if it's not long, yes it's more user-friendly to include the. pre-installation part in.
Here is an example that originally I expected this part (prerequisite) to be. Example

so does he needs to change this ?

[Rohitesh-Kumar-Jain]

@proudofsimin do you approve PR to get merged?

[lijiarui]

I thinks we should change this node/proj/dir to a more normal dir.

[sbis04]

I mean node/proj/dir is just a placeholder, it should be replaced by the user's project directory while executing this command. @lijiarui it would be nice if you can suggest what I can replace this with.

[lijiarui]

How about something like this:

cd <your wechaty dir>

[lijiarui]

How about something like this:

cd <your wechaty dir>

[sbis04]

I have made the changes.

[Rohitesh-Kumar-Jain]

I don't understand why we are documenting updation of node.js and npm, if you want to keep it you can keep it, but it wasn't required.

[Rohitesh-Kumar-Jain]

Another question I have is, where the user will be headed to after the end of this documentation? What is he supposed to do after reading this much?

[sbis04]

I don't understand why we are documenting updation of node.js and npm, if you want to keep it you can keep it, but it wasn't required.

It is required because of the above points that I have written in response to the @proudofsimin's comments. This is also followed by the Django docs (using the Divio format).

[sbis04]

Another question I have is, where the user will be headed to after the end of this documentation? What is he supposed to do after reading this much?

If you see the above screenshot, I have suggested users to head over to the tutorials after their installation is complete.

[Rohitesh-Kumar-Jain]

It is required because of the above points that I have written in response to the @proudofsimin's comments. This is also followed by the Django docs (using the Divio format).

They have just given a link for python installation rather than documenting how to install python.

The reason I opposed documenting updation of node.js and npm are:

1. It makes documentation look verbose.
2. If the document contains an installation of external tools, that becomes outdated with time, so it's a good practice to add links to official installation guides (like in that Django docs), so that we don't have to maintain the installation of the external tool.

Like this command in the doc: curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.35.1/install.sh | bash it's for version 0.35.1 ? It will become outdated in some time and will require maintenance in the future.

[Rohitesh-Kumar-Jain]

That screenshot was of a quick installation guide.

Even in their full installation guide they have just given the link for installation rather than documenting the process.

I went through the Django documentation and was not able to find any documentation for installing python and pip (which is analogous to node.js and npm in this case).

Instead of sharing the link to general documentation of Django documentation or any other project, I would be glad if you may show me the exact links.

[sbis04]

Yes @Rohitesh-Kumar-Jain, I agree this makes the docs a bit verbose. Actually, the reason I added the entire instruction for updating Node.js instead of a link because Node.js doesn't have any official guide for updating it. Earlier I searched a lot but only got third-party guides for it. So, if the users are on a lower version of node then they might be finding it hard to update to the latest version.

And, yes the command for installing NVM will be outdated over time as it contains the version, so for that I can add the official installation doc link.

Today, after a bit more searching I got two pages inside the npm docs:

• Try the latest stable version of npm
• Try the latest stable version of node

So, should I use these instead of the entire instruction in the updating section? (I guess now adding these makes more sense)

[Rohitesh-Kumar-Jain]

If you want to keep the documentation you can keep it no harm, I was just telling you that It isn't advisable to add instructions to install prerequisites.

What I suggest is at least remove screenshots in the installation of node and npm, they are unnecessary and making the documentation long.

[proudofsimin]

Hi @sbis04,
Thank you for your research about this part. The reason why I mentioned to use a link instead of document ourselves is that it's a waste of your time and it's unrelated to the project. Long paragraph and a lot of words sometimes scare away and distract users, so that's why we try to keep the pages clean and clear with only necessary instructions. But the installation npm and Node.js part seemed tolerable, I'm fine with either you wanna keep it or rewrite it with the links.
However, On the other hand, I would still encourage you to add an instruction after your introduction :

Before diving into the tutorials, you will need to install a few build tools. This guide will show you complete installation process of the minimum tools required to start building your own bots. If you have already installed Node.js 12.0 or higher, then go to Install Wechaty.

Since the Install Node.js title is more visible than the sidebars.

[sbis04]

Hi @proudofsimin @Rohitesh-Kumar-Jain @lijiarui I have done the suggested changes and made this page more concise. As I had found the links for getting the latest stable version of Node.js and npm, and they are officially maintained by npm, so I have added them and removed the updating section. Let me know your feedback.

The current version looks like this:

[proudofsimin]

Thank you. This is spectacular.

[lijiarui]

Good job! It's very clear to me!

Btw, I think maybe https://github.com/wechaty/wechaty.js.org/pull/888 duplicate with this part. Could you help @shwetalsoni improving her part pls?