User Guide
-
Hi @mschwartz ! Thanks for the kind words.
Unfortunately I don't think we have anything like that at the moment. It's hard enough to get developers to write technical documentation (exhibit A here) much less user documentation.
Our excuse is we try to make the interface intuitive, but of course, this is not always the case.
If there were some interest in the idea, we could set up a user documentation portal (alongside docs.nodebb.org, or even just within it), but getting the content written and kept up to date is the real challenge.
-
Sorry to hear that.
I made a category “how to use the site” where I post a few tricks/tips and then let users ask questions about how to do ….
So far, my alpha testers haven’t really had any problems, but my users will ultimately be 55+ years old and maybe not so technical. I can make $100/pop just programming AV remotes for some of these people
-
Also, if I had any one gripe, it’s that the code is very old style (I can hack on it if need be though) and the rebuild is kind of a painful step to have to do. Just a restart would be better
I think I saw some mentions of a TypeScript port in the repo, but I don’t know how far that’s coming along.
Still, the software as-is is really really good.
-
Not typescript, uses grunt, not using React or Svelte or another modern framework. I see it looks like jQuery is used?
I can work with the code, and I really appreciate it for how it works for administrators and users and there are a good number of plugins (3rd party support).
-
Also, I did find this:
http://openwis.github.io/openwis-documentation/assets/TC201703-NodebbNotes.pdf
-
Fwiw react was a year old when NodeBB began. Svelte and Vue are newer, which means these architectural decisions were already made and it is an order of magnitude more difficult to switch and adopt.
We try not to jump on the latest new thing (which is ironic since the first data store we supported is redis), because we don't know whether it will be around in several years time.
jQuery we're slowly preparing to drop, but no firm commitment there.
When we started NodeBB, AngularJS was the hot new thing and you were an idiot if you didn't use it.
Angular.
Angular 1.
We all know how that ended up.
-
Also, you can totally call me old fashioned here, but I prefer not to use monolithic frameworks for front end logic. There are lots of benefits but I feel that there are lots of hidden overhead costs that you cannot take into account until you are already well-invested in it.
Many of these frameworks are highly opinionated, which is both a strength and a weakness.
One time early in my career I went all in on this cool framework called MooTools. I got burned when jQuery won out and I discovered I didn't know jack squat about writing actual javascript.
Fool me once shame on me. Fool me twice you...
... you.. can't get fooled again... 
-
I’m not trying to be critical of the product. It’s just my observation. You asked why I thought was old stuff and I answered!
I never ever used angular or wanted to. WebComponents always looked like the ideal to me.
At this point, React and NextJS are mature enough. I’m really into Svelte these days.
FWIW, I used to work for Sencha as a framework engineer. I worked on the ExtJS and Sencha Touch frameworks.
Those were basically killed by React.
Edit: Twitter Bootstrap is a framework, with opinions on the components it provides. The major version releases weren’t that compatible with previous versions.
Cheers
-
Sorry, you're right, I bristled when you pointed out that we used old tech. It happens a lot from people who really just think we should be using the latest js framework.
There's a lot of really cool things that came of age in the past decade. Webpack being one of them. We'd love to try them all, but we sadly don't have the time and energy to do it
-
@mschwartz one of the issues with migration to TS is the plugin system. NodeBB is using some of the flexibility of CommonJS that becomes a liability when adding server-side builds. Plugins use
require.main.require, and I'm honestly not sure how well this works with TypeScript - it definitely doesn't work with IntelliSense (so plugins wouldn't even get the typing by default unfortunately), but I don't remember if I was testing tsc when I looked into using ES6 imports and building server-side code...It'd be relatively simple to go Svelte way and use JSDoc for type checking with TS but without compilation though, just some work on adding the types and fixing issues found that way
Still, one would need some more work for it to help plugin developers and not just core. -
@oplik0 said in User Guide:
@mschwartz one of the issues with migration to TS is the plugin system. NodeBB is using some of the flexibility of CommonJS that becomes a liability when adding server-side builds. Plugins use
require.main.require, and I'm honestly not sure how well this works with TypeScript - it definitely doesn't work with IntelliSense (so plugins wouldn't even get the typing by default unfortunately), but I don't remember if I was testing tsc when I looked into using ES6 imports and building server-side code...It'd be relatively simple to go Svelte way and use JSDoc for type checking with TS but without compilation though, just some work on adding the types and fixing issues found that way
Still, one would need some more work for it to help plugin developers and not just core.I’ve been doing some significant development using Svelte. I really like it a lot.
FWIW, I was a framework engineer for Sencha. I worked on ExtJS and Sencha Touch frameworks (many many pull requests I did were merged).
The thing about plugins…. Typescript and JavaScript are interoperable. I don’t see why you can’t interact with the current plugin scheme from a Typescript port of NodeBB. And you could also allow plugins to be in Typescript or JavaScript.
Maybe the big deal is transpiling the code from .ts to .js, but NodeBB already has a rebuild requirement when adding things via admincp.
-
@mschwartz Switching to Vite sounds like an easy thing (and very tempting, the construction time will be incredibly shortened!), but he says to switch from CommonJS to ESModules, which means a lot of work in adjusting the dependencies and apparently breaking all the existing plugins...
-
@mschwartz @josef sometimes I pine for the days before we wrote
./nodebb build. Back in those days, we actually had NodeBB build all the assets during the startup phase... there just wasn't that much that needed to be compiled, modules linked, etc../nodebb startwould bring you a fully functional NodeBB with fresh assets in under a second.Such is progress, no? Still, I miss it.
-
Secondly, as @PitaJ will attest to, @baris and I are a bunch of old dogs. We've been at this nearly ten years, and while that's not a lot of time in the real world, in tech it means we're dinosaurs
He had to drag us kicking and screaming to implement ESLint, and we're all the better for it.
Maybe @baris isn't an old dog, he dragged my ass kicking and screaming to Bootstrap5/webpack, so
miracles can happen.
