Real need for better docs for noobs

[LeeM]

Hi,

am really keen to use Nodebb, it looks to me to be in a class of its own.

My only (constructive) criticism is that the documentation is aimed at users who are proficient with the languages and systems used to run the software. As a developer that is used to working with php/mysql; Node.js, Linux and Redis or MongoDB databases means absolutely nothing to me and probably a significant proportion of other users that are use php based forum software - this will most certainly be affecting your market reach, which has the potential to be massive if only there were docs to make it easy to install for everyone, including complete noobs like myself.

I did discover a dummies guide, but even this assumes knowledge that many users (including me ) will be unfamiliar with, and the regular install guide might as well have written in Martian, as it made no sense at all. My personal preference is to test software on a local PC based server, but I've not been able to locate such a guide.

My advice would be to create a guide that includes everything needed to install Nodebb, not assume any prior knowledge of any of the systems required for its installation, for example the dummies guide assumes that users want to install on paid hosting. I also found that I was unable to install putty on my PC, so I'm now not even able to use the paid for installation service you guys provide (which I was going to do, yes I am that keen to use it), i.e. what's the point if I cant access the server?

Amazing software, but too sharp a learning curve for me I'm afraid, if it was easier to install I'd convert in an instant

Lee

[a_5mith]

What's difficult about copying a command 1 line at a time into ssh and pressing enter?

There is no one guide fits all. It's tough to account for server operating systems like Ubuntu and other distros.

[LeeM]

@a_5mith said:

What's difficult about copying a command 1 line at a time into ssh and pressing enter?

There is no one guide fits all. It's tough to account for server operating systems like Ubuntu and other distros.

Your response illustrates my point perfectly.

[a_5mith]

Does it?

The guides you see in the documentation explain how to install nodebb. I don't believe the nodebb guys need to teach people how to use ssh at the same time. There's a plethora of guides for that on the Internet.

In addition: to assist those that don't wish to learn new languages and operating systems. They will host it for you for a monthly fee. Which is very nice if them.

[frissdiegurke]

In my opinion there are enough easy-to-follow guides for local installation, cloud installation or even docker-setup.

In your case you'll need the local installation guide for windows (I guess you're using windows because of your putty comment).

I agree that the windows-guide is a difficult one to follow since windows doesn't have anything to make your life more easy (like a well-working package-manager, etc.).
But your conclusion of missing guides on NodeBBs side is the wrong direction. You should expect of your OS to give you some hints on how to install software on it.

You simply cannot expect of a software to describe how to install it under all circumstances.
And windows is NOT the most-used OS for web-services. It's just (sadly) one of the most used OS in personal area and surely not optimized for development, network-connections or web-hosting.

Did you expect of your php-scripts to explain how to install them on any OS with any php-environment? Should any php-script come with an explanation how to install apache/lampp/xampp/whatever on any OS?

The only valid reason (from my point of view) for NodeBB itself to keep and manage those installation guides is because it's distributed as a git-repository and has a few dependencies that need to get installed additionally. And this is the most important part of the links above.
But you won't see any non-single-line description how to install those dependencies since it's not within NodeBBs responsibility (and capability since the installation-guide would need to keep up-to-date).

You don't need to run Windows for NodeBB (and I'd highly disadvise) but if you're using Windows you shouldn't expect of a software to describe its own installation as far as it's the default way of installing software.
If you want to use a cloud-service to run your NodeBB you shouldn't expect NodeBB to explain how to use that cloud-service or connect to it from any OS. It's a task of the cloud-service to give you a short introduction how to get a running connection. And even those shouldn't need to explain how to install putty on windows.

Hence that NodeBB delivers some guides on how to connect to a few well-known cloud-services is an overhead that doesn't need to be, it's an additional service of the NodeBB devs/community. But "Real need for better docs for noobs" should be out of question. You should assume that anyone who uses an OS should be "proficient with the system". If they're not they need to learn how to use their favorite search-engine or switch to another system that's more comfortable (and most likely doesn't cost anything ).

In my opinion NodeBB should even have less docs about installation since I don't want users without any clue what they're doing to setup an online service.
This privilege should be dedicated to those who have learned to understand what they're doing since it comes with a great responsibility and a bunch of work (that isn't any-near done after the setup) to run an online service.
To run an easy-to-setup platform like NodeBB doesn't take the responsibility of you to be aware of internet-policy, copyright laws or worst-case-scenarios.
So all in all my opinion contains that "noobs" shouldn't think about running a platform at all before getting familiar with the system and the platform.

But don't take this as an overall opinion of the NodeBB-community, it's my personal one and I expect a broad pool of (different) opinions about that to be present here

---

I should really learn how to write short answers and how to not make a discussion about windows vs linux within each post xD

[PitaJ]

I (sadly) use windows for all of my web development and I hate it. But I hate restarting into my dual boot and running Linux in a VM even more, and I have to have my games, so, I guess I'll have to deal with it.

[Oroton]

@a_5mith said:

What's difficult about copying a command 1 line at a time into ssh and pressing enter?

There is no one guide fits all. It's tough to account for server operating systems like Ubuntu and other distros.

I think you fail to understand what he's saying.

For someone new to this. especailly from the
"upload files via FTP,"
"create DB via MySql"
"go to url and press install buttom"
like phpbb, xenforo, vb, ipb, vanilla, mybb, Simple Machine. And more.

Comapred to the ease of that Nodebb is complicated.

They wont even not what command line is or Docker or SSH

Especially for windows users

The guides assume you know how git works or command line.

I know I for one 2 weeks ago. was in that situation.

[LeeM]

@frissdiegurke said:

Did you expect of your php-scripts to explain how to install them on any OS with any php-environment? Should any php-script come with an explanation how to install apache/lampp/xampp/whatever on any OS?

Actually that's a really good point, guess I'll have to start from the beginning, thanks appreciate your thoughts

[LeeM]

@Oroton said:

@a_5mith said:

What's difficult about copying a command 1 line at a time into ssh and pressing enter?

There is no one guide fits all. It's tough to account for server operating systems like Ubuntu and other distros.

I think you fail to understand what he's saying.

For someone new to this. especailly from the
"upload files via FTP,"
"create DB via MySql"
"go to url and press install buttom"
like phpbb, xenforo, vb, ipb, vanilla, mybb, Simple Machine. And more.

Comapred to the ease of that Nodebb is complicated.

They wont even not what command line is or Docker or SSH

Especially for windows users

The guides assume you know how git works or command line.

I know I for one 2 weeks ago. was in that situation.

Thanks Oroton, you said what I meant in a lot less words and a whole lot better

[Oroton]

I'm still a "Noob" myself in that sense. But i may make a tutorial for windows users, that takes them from that state, to a state where they meet the basic requirements for the tutorials listed.

I'm not developing with NodeBB, but it is the chosen BB I will when I finish my project.

[LeeM]

What makes a great Open Source project? Is it simply the software and the development team? No it's the users that make a project like Nodebb special. If I were here to troll, then that's fine I'd accept the negative comments about not being able to do this or that, but I'm here because I think Nodebb is amazing and I'd love nothing more than to use it for my community.

My point and that which Oroton helped to explain is that there's probably tens of thousands of users that love the look of Nodebb, but can't understand how to install it because they're used to using phpbb, xenforo, vb, ipb etc. and if you look at how popular php based forum software is (they dwarf Nodebb in their usage) you'd be a fool to discount them as potential users, which not having documentation aimed at them is doing.

Personally I think that's a big mistake and a very poor business decision.

[yariplus]

@LeeM

I think they have made the best possible decision. Those other forums can be installed by a (Hosting provided) control panel without touching the command line at all. NodeBB runs on a completely different platform, they can't just make a cPanel installer afaik, which would be the best possible solution. So, they've done the next best thing and offered their own managed hosting.

I'm not saying the documentation is fantastic though, it could definitely use some improvements. (Specifically, it relies on those single command line entries to work, and doesn't give you much to go on if something derps up.) BUT, it is still much better imo then other docs I've seen for other forums when doing a non-control panel install.

[Oroton]

@yariplus said:

@LeeM

I think they have made the best possible decision. Those other forums can be installed by a (Hosting provided) control panel without touching the command line at all. NodeBB runs on a completely different platform, they can't just make a cPanel installer afaik, which would be the best possible solution. So, they've done the next best thing and offered their own managed hosting.

There are significant reasons why people wouldn't leave their board for a manged hosting board. It's not exactly the same and literally would appeal to less then 1% of the thousands of users that use the other formats.
The reason they use those is mostly how cost effective they are, and the amount of control they have with it.
I don't think a cPanel installer is the answer, but a good tutorial that takes them slowley through the process that is from their site. with The dumped data to a new install on x host.

I'm not saying the documentation is fantastic though, it could definitely use some improvements. (Specifically, it relies on those single command line entries to work, and doesn't give you much to go on if something derps up.) BUT, it is still much better imo then other docs I've seen for other forums when doing a non-control panel install.

I've used all of those forums I mentioned and everyone has a very comprehensive easy to use install.
NodeBB needs a better one. But that isn't to say it should be left up to the NodeBB team.
It is a community software. The community could take some responsibility to compile a list/step by step guide on what to do.

I know I would rather NodeBB developers spend their time on NodeBB core not a tutorial.

[LeeM]

Interested to note Andrew Rodrigues comment in the dummies guide;

"So I’ve been wanting to write a NodeBB setup guide for someone with pretty much no development experience at all – potentially somebody who’s never even seen a terminal in their life. I’m hoping it will reduce the barrier of entry for those wishing to try NodeBB out."

So there is intent by the development team to provide info for people like me.

However the dummies guide makes one very big assumption - "that those wishing to try NodeBB out " - want to pay to try it - yes I agree ten bucks isn't much, but still why pay when there's a chance that Nodebb wont work on your operating system?

Andrews dummies guide doesn't include any minimum requirements for installation, for example I might be wrong, but Nodebb can only be installed on newer versions of windows? When I visited the Putty site there were numerous versions to download the majority of which were X86 and only one X64? Which should be used? Basic info like this is essential for a dummies guide!

I assure you I'm not a noob in every respect, I'm a highly regarded developer in my own field, I also run a popular open source project , and have been an active developer for almost 25 years, so if I'm struggling with it, imagine how an average user will be feeling, especially one that has "never even seen a terminal in their life"

So yes there is intent by the development team, but I think they have underestimated how much knowledge is required to use Nodebb.

I'm not going to comment about this anymore, it is completely obvious to me that the documentation isn't aimed at a huge proportion of potential users and for this reason I won't be using it. While this in itself is no loss, remember I could potentially reflect the opinion of hundreds of thousands of users, the only difference is that I care enough bring this issue to the attention of the development team, what they do with this info is entirely up to them.

I also think it speaks volumes that none of the admins or developers have made a comment.

[a_5mith]

Putty is a tool for connecting to a server via ssh, it doesn't host your nodebb for you.

It's not nodebbs fault that you only know how to use FTP and run install.php from a browser.

There are no minimum requirements for installation. if you want to install on windows, follow the windows guide:https://docs.nodebb.org/en/latest/installing/os/windows8.html

[Oroton]

while i agree with you completely,

if you have been developing for 25 years you are doing yourself a disfavor not learning command line/terminal.

pretty much any host/vps or dedicated will cost you.

All the new technologies, will require you to learn this new way of interacting with your host. And you need to move past static websites, and move to dynamic, interactive technologies.

think of it like moving away from pushrod carborettors to twin cam fuel injected.

and this thread is only a day or so old. Give the developers a bit of a break. I bet they don't get paid to do this, and probably have their own jobs

[LeeM]

@Oroton said:

while i agree with you completely,

if you have been developing for 25 years you are doing yourself a disfavor not learning command line/terminal.

pretty much any host/vps or dedicated will cost you.

All the new technologies, will require you to learn this new way of interacting with your host. And you need to move past static websites, and move to dynamic, interactive technologies.

think of it like moving away from pushrod carborettors to twin cam fuel injected.

and this thread is only a day or so old. Give the developers a bit of a break. I bet they don't get paid to do this, and probably have their own jobs

Hi Oroton, lol yes I really am that old

I realise host costs, the hosting fees for my OS project are very high, so it's not something I get hung up on ordinarily, I'm just not that keen on having to pay to test software.

Will definitely look at learning the terminal and other associated technologies, will need to get a new computer first though

Thanks for supporting me in this discussion, like I said I'm not going to push the matter of the documentation, instead I'm creating a skin that replicates the NodeBB look with Vanilla 2, which for me is a lot easier that learning new tech.

Been a pleasure and good luck with your projects, Lee

[Oroton]

@LeeM

openshift is free for up to 3 running projects

[LeeM]

@Oroton said:

@LeeM

openshift is free for up to 3 running projects

Awesome tip, am working my way through the install as we speak, having problems with installing ruby and an ssl error, but I'm getting there, ur a star

[LeeM]

WOW these programs are full of bugs and problems, finally managed to install all of the software required to use Openshift only to find there's issues with this too lol

Have you used Openshift?