Misinterpretation/Misunderstanding Of The MyBB Documentation

[Serpius]

Regarding the misinterpretation/misunderstanding of the MyBB documentation issue.

Has anyone from the developer team thought about asking a few admins (such as myself) to review the MyBB documentations and see if us "peons" can understand how to install/fix/modify the setup of their MyBB website?

There have been so many threads and posts over a LONG time about people not understanding certain aspects of the documentation of MyBB. 

I am wondering if the developer team had thought about permitting an "outside non-developer" team (2-3 admins) to review the documentation and ask for clarification on any part of the procedures that one might not fully understand.

I realize that this might not be the "perfect" solution to ridding all of the "Help Me" postings, but a better understanding of the documentation may go a long way of maintaining one's MyBB website that much easier.

If this is the incorrect forum, please move this thread to the appropriate forum.

[Wires]

I would see this more of a community team thing to do, but if you don't understand something or think someone else may not understand something then feel free to provide a link to it so we can review it. Or even submit a PR.

Edit: Just sent you a PM.

[linguist]

The question is: what audience is that documentation targeted at? Admins who know what "chmod that folder to 666" means or people who need a step-by-step instruction? How much skill can/should be assumed? Testing the documentation with experienced admins cannot make sure that rookies will find it useful, too. I'd favor a wiki system where (trusted) community members can modify the pages. Over time, that will make sure the instructions will have the right level of complexity or exist in varieties like "quick guide" vs. "detailed guide".

[Wires]

The question is: what audience is that documentation targeted at? Admins who know what "chmod that folder to 666" means or people who need a step-by-step instruction? How much skill can/should be assumed? Testing the documentation with experienced admins cannot make sure that rookies will find it useful, too. I'd favor a wiki system where (trusted) community members can modify the pages. Over time, that will make sure the instructions will have the right level of complexity or exist in varieties like "quick guide" vs. "detailed guide".

I think the documentation is somewhat pretty clear and understandable, even then, at the moment I'm making PRs and starting to ask certain forum admins I know if they can understand certain docs. Forum administration is much more than just drag n drop nowadays, referring to your point about "admins who know what chmod that folder to 666" - when are users going to start taking it upon themselves to go to Google and search "chmod" and so forth? Even then, the Install doc actually gives you multiple ways to do so just to clear up that example.

If we can start using this thread to drop some links to pages which aren't clear, concise, and in-depth enough that will be really helpful. Everyone seem to have a point but no one has given any references or pages just yet.

[Serpius]

The question is: what audience is that documentation targeted at? Admins who know what "chmod that folder to 666" means or people who need a step-by-step instruction? How much skill can/should be assumed? Testing the documentation with experienced admins cannot make sure that rookies will find it useful, too. I'd favor a wiki system where (trusted) community members can modify the pages. Over time,  that will  make sure the  instructions will have the right level of complexity or exist in varieties like "quick guide" vs. "detailed guide".

I think the documentation is somewhat pretty clear and understandable, even then, at the moment I'm making PRs and starting to ask certain forum admins I know if they can understand certain docs. Forum administration is much more than just drag n drop nowadays, referring to your point about "admins who know what chmod that folder to 666" - when are users going to start taking it upon themselves to go to Google and search "chmod" and so forth? Even then, the Install doc actually gives you multiple ways to do so just to clear up that example.

If we can start using this thread to drop some links to pages which aren't clear, concise, and in-depth enough that will be really helpful. Everyone seem to have a point but no one has given any references or pages just yet.

@lingquist - For people who need Step-By-Step instructions.
We both have seen and read numerous threads/posts by people who are doing the MyBB thing for the very first time with little or no knowledge of PHP, FTP, CSS, templates and so on. 

I am wanting to assist those kinds of people that want to set up a forum based website, but have little knowledge of doing this. 

In order for MyBB to grow, we must try our best to make MyBB as user-friendly as possible. 
The easier for people to install and maintain their MyBB website, the more people will use MyBB and support the growth of MyBB.

We cannot and should not ASSUME that people know certain things about things like CHMOD, modifying CSS or templates. That's not fair to those people wanting to create a forum based website for whatever reason they may have. We need to provide proper documentation for those kinds of things. 

No, it does not mean that MyBB has to be ALL THINGS to all people, but give those people proper direction in establishing their website in the ever increasing and crowded internet.

@Wires - As we discussed before, I am reviewing all of the MyBB documents and will be providing the developer team my suggested changes and/or revisions to the documentations. 
It's going to be a long process, not something that will happen overnight.

Some parts of the documentation do not need to be changed, but other parts do or at least be clarified for people who are not technically inclined.

Also, correct me if I am wrong, but I am not aware of any other translated MyBB documentations. It's only in English if I am correct. 

We should allow other people to translate the documentation into their native language and submit the translated documents for review and approval.

That translated documentation can be stickied somewhere in MyBB so that people can easily access it. 
In fact, a live link from the translations can be embedded into the English documents that will take the non-English users straight to that forum that contains their translated documents.

Just a small list of the top 5 spoken languages in the world:
1. Chinese (Mandarin)
2. Spanish
3. English
4. Hindi
5. Arabic

Translating MyBB documentation into those 5 languages will cover a large majority of the world population.

Just my 2 cents...

[Euan T]

It's also worth noting that the documentation is all on GitHub and can be edited by anybody. If you find some page(s) that aren't clear or Ould be improved, we're more than happy to receive suggestions and edits that will likely be merged in: https://github.com/mybb/docs.mybb.com

We're a fairly small team, and maintaining and managing documentation is a big job. Different people obviously understand and interpret information differently, and there's no way that we'll be able to provide the perfect documentation for absolutely everyone. Having it available publicly and allowing public contributions is the easiest way for us to improve.

[linguist]

Forum administration is much more than just drag n drop nowadays,

That would be one good warning to be put prominently in the download section as well as the documentation. From watching the questions here, I got the impression that a lot of prospective forum admins have not much of an idea but high expectations to get an out-of-the-box easily installed and running forum they can administrate without any background knowledge how a web server, PHP, CSS and so on work. It'd be an honest and fair warning that this is not what they'll be getting.

referring to your point about "admins who know what chmod that folder to 666" - when are users going to start taking it upon themselves to go to Google and search "chmod" and so forth?

You know the sad truth of the answer: some – never. The question is whether we want to accommodate these users or not.

[Devilshakerz]

The question is: what audience is that documentation targeted at? Admins who know what "chmod that folder to 666" means or people who need a step-by-step instruction? How much skill can/should be assumed? Testing the documentation with experienced admins cannot make sure that rookies will find it useful, too. I'd favor a wiki system where (trusted) community members can modify the pages. Over time,  that will  make sure the  instructions will have the right level of complexity or exist in varieties like "quick guide" vs. "detailed guide".

Basic maintenance and management shouldn't require much technical knowledge - it's difficult to apply that to MyBB 1.8 given the caveats that were the reason why rewriting everything was considered, but that should be our aim after things get cleaned up.

Meanwhile, all technical terms (like file permissions) can be linked to reputable sources that explain usage on popular platforms.

[Serpius]

referring to your point about "admins who know what chmod that folder to 666" - when are users going to start taking it upon themselves to go to Google and search "chmod" and so forth?

You know the sad truth of the answer: some – never. The question is whether we want to accommodate these users or not.

Unfortunately, that is the sad truth.

That's why lately, I have been posing the question to these "newbies" or "the clueless", 'Did you read the manual/instructions of MyBB?'

Often, the answers would be one of the following... 'No', 'Too difficult to understand', 'Not in my language', 'Too technical for me', and others that I don't remember now.

The question is: what audience is that documentation targeted at? Admins who know what "chmod that folder to 666" means or people who need a step-by-step instruction? How much skill can/should be assumed? Testing the documentation with experienced admins cannot make sure that rookies will find it useful, too. I'd favor a wiki system where (trusted) community members can modify the pages. Over time,  that will  make sure the  instructions will have the right level of complexity or exist in varieties like "quick guide" vs. "detailed guide".

Basic maintenance and management shouldn't require much technical knowledge - it's difficult to apply that to MyBB 1.8 given the caveats that were the reason why rewriting everything was considered, but that should be our aim after things get cleaned up.

Meanwhile, all technical terms (like file permissions) can be linked to reputable sources that explain usage on popular platforms.

In a perfect world, basic maintenance and management shouldn't be all the hard to do.

But since we don't live in a perfect world,  there are so many parts of MyBB that it does take a long time (well, it did for me) to learn all of the 'ins and outs' of MyBB, especially in the AdminCP.

Then you add in the maintenance of the themes, especially the annoying fact that many theme creators put in their own default logo that states the name of the theme, but it's difficult for many to modify it to fit the name of their own website.