Real need for better docs for noobs

  • Community Rep

    @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.


  • @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.


  • 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.


  • 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


  • 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


  • @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 😄


  • @LeeM

    openshift is free for up to 3 running projects


  • @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 😄


  • 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?


  • @LeeM

    I believe it is only

    Ruby and Git
    that you should install. If you are after a really good tutorial for what to install use

    and to run it on openshift, the docs is usefull (don't skip the first step) Then cut to openshift on PaaS

    When it says to Exit SSH, close it down. and open it again
    (when you get to the CD) section


  • yeah I gave up on that and paid for digital ocean after all, followed the dummies guide and I can't set Nodebb up, getting lots of errors, there's actually quite a lot of stuff missing from that guide and I've had to search and solve using these forums, probably had 20 ERR messages during installation and when I typed "node app --setup" it replied with "The program node can be found in the following packages."

    This software certainly isn't for the weak of heart lol

    Thanks for the links though if I can't solve this I'll retry with your tips and tutorials.


  • @LeeM If you search this forum i've made the setup in openshift without error, following the guide and some suggestions another users kindly gave me.

    Regards.


  • @Lee_m.

    I'll take a look at the docs when I get in and make sure they still work. If needs be I can get you set up and running. Then you change your server passwd once it's up and running. Installation should only take about 5 minutes. 🙂

  • GNU/Linux Admin

    @LeeM My apologies for the lack of a response (though of course, it was the weekend for 2/3rds of those days 😉 )

    We do get excited when new people want to try NodeBB, but as others have kindly pointed out, it would be a full-time job if I were to devote my full attention to helping somebody install NodeBB. This is not to say that I actively don't help others, it's just that concessions have to be made if we want to keep developing NodeBB 😄

    This is why I'm especially grateful to the users who spend their time here, donating their time to helping others get up and running. They don't get compensated for their time, so it is very meaningful.


    Now, onto the matter of getting you up and running. I will fully admit that there exists a moderate learning curve, especially if:

    1. You come from a LAMP-stack background, or
    2. You are not technologically inclined (e.g. a computer user, not a developer)

    For those that fall into the second grouping, getting set up is an almost insurmountable task, and I mention this whenever I can:

    WordPress installations weren't always simple one-click affairs. When I first discovered WordPress, or phpBB, or similar softwares, I had to sign up for a host, log in via ssh (what's PuTTY?), install mysql (what's mysql? what's phpmyadmin? what is apt-get?... and apt is the simpler way of installing things...), create a database (how do I do that?), set up apache (what's apache?), finangle the configs until it could serve the right folder, debug for hours as to why it's just showing "It works!", run the install script, and then and only then, start tweaking my install.

    But nowadays, cloud hosting providers have distilled all of this into a single step. We've done the same with NodeBB on our hosting platform, and this is why we recommend going with our hosting if you don't want to deal with the headache of setting NodeBB up.

    As a point of reference, back in those days, it took me hours (spread over days) to get everything set up properly. I was learning then, as you are learning now. Knowledge doesn't come quick, or free!

    Personally, I wish installing NodeBB were easier. However, there are still many prerequisites that we simply cannot get rid of. Knowing what ssh is, and how to use it, is one. Over time these problems will be nullified (much like how Wordpress is a simple one-click install), but until then, you will have to bear with us 🙂

    Many of the installation guides are community-driven. That is, they depend on the hard work of interested parties to ensure that the guide is up to date, and... you know, works. I install NodeBB on DigitalOcean boxes, and (very) occasionally, on Heroku, so those are the two I support.

    Everything else is just a bonus 😄

  • GNU/Linux Admin

    @LeeM said:

    ... and when I typed "node app --setup" it replied with "The program node can be found in the following packages."

    Sounds like you didn't install node.js.

    Are you logged in as root? Your command line should show something like [email protected]:~#. Then you'll have to install the prerequisite software required for NodeBB:

    # sudo apt-get install git nodejs nodejs-legacy npm redis-server imagemagick build-essential

    Note: Keep in mind that # is not part of the command. Lots of people preface commands with # to mean "run this as the root user". If I were to tell you to run a command as a regular user, I would use $ instead. Just a relevant factoid.

  • GNU/Linux Admin

    Okay, again, I will admit this can be intimidating for new users:

    Selection_028.png

    ... especially because your desktop OS is Windows, but you're looking to install it on DigitalOcean, which is (probably) running Ubuntu.

    I'm looking into providing a CloudInit script in order to distill the entire installation process into a single line. Stay tuned.


  • You think installing NodeBBs confusing. Try making sense of this:

    https://www.youtube.com/watch?v=qjOZtWZ56lc


  • @a_5mith said:

    @Lee_m.

    I'll take a look at the docs when I get in and make sure they still work. If needs be I can get you set up and running. Then you change your server password once it's up and running. Installation should only take about 5 minutes. 🙂

    Wow ... That's a very generous offer 😄 How do I do that and does it matter that I already tried to install it once? Many, many you're too kind ...

  • Global Moderator Plugin & Theme Dev

    I'm gonna build a GUI installer for Windows that will also be an update manager. It will be built in NW.js, so it can be ported to Linux, OSx, etc.


  • @julian said:

    @LeeM My apologies for the lack of a response (though of course, it was the weekend for 2/3rds of those days 😉 )

    We do get excited when new people want to try NodeBB, but as others have kindly pointed out, it would be a full-time job if I were to devote my full attention to helping somebody install NodeBB. This is not to say that I actively don't help others, it's just that concessions have to be made if we want to keep developing NodeBB 😄

    This is why I'm especially grateful to the users who spend their time here, donating their time to helping others get up and running. They don't get compensated for their time, so it is very meaningful.


    Now, onto the matter of getting you up and running. I will fully admit that there exists a moderate learning curve, especially if:

    1. You come from a LAMP-stack background, or
    2. You are not technologically inclined (e.g. a computer user, not a developer)

    For those that fall into the second grouping, getting set up is an almost insurmountable task, and I mention this whenever I can:

    WordPress installations weren't always simple one-click affairs. When I first discovered WordPress, or phpBB, or similar softwares, I had to sign up for a host, log in via ssh (what's PuTTY?), install mysql (what's mysql? what's phpmyadmin? what is apt-get?... and apt is the simpler way of installing things...), create a database (how do I do that?), set up apache (what's apache?), finangle the configs until it could serve the right folder, debug for hours as to why it's just showing "It works!", run the install script, and then and only then, start tweaking my install.

    But nowadays, cloud hosting providers have distilled all of this into a single step. We've done the same with NodeBB on our hosting platform, and this is why we recommend going with our hosting if you don't want to deal with the headache of setting NodeBB up.

    As a point of reference, back in those days, it took me hours (spread over days) to get everything set up properly. I was learning then, as you are learning now. Knowledge doesn't come quick, or free!

    Personally, I wish installing NodeBB were easier. However, there are still many prerequisites that we simply cannot get rid of. Knowing what ssh is, and how to use it, is one. Over time these problems will be nullified (much like how Wordpress is a simple one-click install), but until then, you will have to bear with us 🙂

    Many of the installation guides are community-driven. That is, they depend on the hard work of interested parties to ensure that the guide is up to date, and... you know, works. I install NodeBB on DigitalOcean boxes, and (very) occasionally, on Heroku, so those are the two I support.

    Everything else is just a bonus 😄

    Hi Julian, many thanks for taking the time to write such a thoughtful response, of course I appreciate you can't dedicate your time to a single user, but in my defense I wasn't asking for help (though it will be very gratefully received), my intent was to point out the docs deficiencies and so help the project grow by opening it up to a larger audience.

    Other than that thanks for the useful tips, still not entirely sure what a lot of it means but I guess I have to start somewhere, but one thing I'll promise you, if I do manage to work out how it all works I'll create an install guide for apache people.

    best, Lee


Suggested Topics

| | |

© 2014 – 2022 NodeBB, Inc. — Made in Canada.