Hello IPB Community and makers of IPB. I'm fan of IP 3.X.X when it first came out in June 2009. Now six month later I still don't see much information on how you go about understanding IP's programs and add-ons that much. I have learned much of what I know by of course knowing about some programming and asking questions which is fine. But their needs to be more information out from IP. I'm going to try and point out the reasons behind this and why I say what I will say.

------------
*Disclaimer*
This is not a rant or other type of fire post just something that I think there should be added and look at in more detail and not just "talk" about, but acted on.
-----------

Okay let get started. First of all the help files that are currently available are great for upper level people who understand what going and stuff is but for novices and beginners there is really nothing there. I will bring up a vbulletin document information. http://www.vbulletin.com/docs/html This material helps the user to understand many thing about the program and look here before they have to ask more details questions. Something like this should be added to IP. Another example is here on the gallery and blogs, how does one do this are that. I see many post about how to turn this on or off but don’t know where it at but as far as the developers and makers they know where it at, so then again the user is lacking a place to look at for information but have to wait to get there question answer on something that the makers and coders should know. There is a saying “Don't assume people know what you know,” do having a manual type people can print or download to a book reader would be in the best interest of everybody in the IPB community.

If not then people like myself, customers, will have to go out to someplace and order a book that someone else came up with and give them our money to learn software that the makers don’t want to give us. IE http://www.packtpub.com/invision-power-board/book I would prefer to give my money to the makers so that it will fund other projects and improve the software.
Again this is not a rant but to get the word out that there needs to be more then what you have and in more details then just trying to do this and post this. There needs to be step by steps guides for other people who don’t know the software to learn how to use stuff correctly and keep running to the forums for questions that could be answer in a book that makes learning it all faster and easy.

I would like to know the view point of the community on this issue and what IP will do next to pass this along or drop the ball. We will see.

The first link I clicked on in that vBulletin documentation (which was just a random entry from the list) took me here:
http://www.vbulletin.com/docs/html/adminlogin
Now personally, I think that entire article is unnecessary, and quite frankly, patronising to users and a waste of the time of whoever wrote it.
I would sincerely hope that someone administrating a website is able to recognise a log in page and know what to do... and if not, well... no amount documentation is going to be enough.

We have a lot of documentation available here (certainly many times more than what we had when IP.Board 3 was released): http://community.invisionpower.com/resources/official.html
We try to document every Admin CP page, we have a database of every error code IP.Board generates and we have developer documentation straight from the developers (which I refer to when developing).

If there's something specific you feel isn't documented which should be, by all means, we're all ears... but I don't personally see a point in documenting every button there is to click ad nauseum. If the product requires that level of documentation, I would think that there is a problem with the usability of the product.

I appreciate that what some feel is the problem is the way in which our documentation is presented (in articles rather than one single manual). We have tried the manual approach before and it had problems:
- It was difficult to update
- It was not searchable (we discovered users found it easier to submit a ticket then find what they wanted in the documentation)
- Trying to direct users to a certain part was a problem ("Go here, download it, you'll probably need to install Acrobat or something to open it, then go to page 3, look at the third paragraph....") - it was easier for us just to copy and paste from it. And because of this, people always relied on us rather than thinking "Oh, last time they just pointed me to the documentation, I'll look there first"
The approach of articles vs. one massive manual is something we prefer a million times over. The general consensus from users is the same (some people from these forums have said they'd want a single manual so they could buy a physical copy and read the entire thing - but 99% of our users have no desire to do that, and just want whatever information they want at a given time) and so I don't think it's something that will change.

The first link I clicked on in that vBulletin documentation (which was just a random entry from the list) took me here:

http://www.vbulletin.com/docs/html/adminlogin

Now personally, I think that entire article is unnecessary, and quite frankly, patronising to users and a waste of the time of whoever wrote it.

I would sincerely hope that someone administrating a website is able to recognise a log in page and know what to do... and if not, well... no amount documentation is going to be enough.

We have a lot of documentation available here (certainly many times more than what we had when IP.Board 3 was released): http://community.invisionpower.com/resources/official.html

We try to document every Admin CP page, we have a database of every error code IP.Board generates and we have developer documentation straight from the developers (which I refer to when developing).

If there's something specific you feel isn't documented which should be, by all means, we're all ears... but I don't personally see a point in documenting every button there is to click ad nauseum. If the product requires that level of documentation, I would think that there is a problem with the usability of the product.

I appreciate that what some feel is the problem is the way in which our documentation is presented (in articles rather than one single manual). We have tried the manual approach before and it had problems:

- It was difficult to update

- It was not searchable (we discovered users found it easier to submit a ticket then find what they wanted in the documentation)

- Trying to direct users to a certain part was a problem ("Go here, download it, you'll probably need to install Acrobat or something to open it, then go to page 3, look at the third paragraph....") - it was easier for us just to copy and paste from it. And because of this, people always relied on us rather than thinking "Oh, last time they just pointed me to the documentation, I'll look there first"

The approach of articles vs. one massive manual is something we prefer a million times over. The general consensus from users is the same (some people from these forums have said they'd want a single manual so they could buy a physical copy and read the entire thing - but 99% of our users have no desire to do that, and just want whatever information they want at a given time) and so I don't think it's something that will change.

Yes sorry about that first link it should have went to "http://www.vbulletin.com/docs/html " An example of what I mean is that in IP. Content, their are features that people don't understand and I get that from just reading the help forums, there is not much then click here or click here help. It should be explain in a better manner. Another example is in IP Gallery their are new features that just came out and people are asking where is this or that, and there should be documentation out on where to find it at, and what some features do. This goes on in all the IP products line. Just something needs to be put out more then what is currently is out. Also screen caps of the interfaces does do wounder when your trying to explain stuff to others, something I urge future articles should be done with more then what is current there.

Well that is the sort of thing we can improve on :)

IP.Content is actually probably our most documented product - in tech support we rarely get a question come up that isn't answered by "go here..." - if there's something you found confusing, what was it? We can certainly write up documentation if something needs documenting.

IP.Gallery's new features aren't documented (publicly) because Gallery 3.1 is not final. When it is, we will update the documentation.

Well that is the sort of thing we can improve on :)

IP.Content is actually probably our most documented product - in tech support we rarely get a question come up that isn't answered by "go here..." - if there's something you found confusing, what was it? We can certainly write up documentation if something needs documenting.

IP.Gallery's new features aren't documented (publicly) because Gallery 3.1 is not final. When it is, we will update the documentation.

Of course what I put up in my last post was an example, the problem is across the whole IP product line. But again, the whole of all the products need more details that what is current there.

Do you have any details?

As Mark has already said, we try to document every ACP page, and we attempt to document the things that need to be documented (while skipping "click the login button to login" type articles). Have you browsed our documentation yet by chance? If you have, and you feel things are underdocumented, the best bet is to tell us exactly what isn't documented that we need to put up more information on.

"You need more documentation"
That is hard to act on.

"Feature xyz should be better documented because I didn't know I had to go to page qrs to use it"
We can do something about that.

If not then people like myself, customers, will have to go out to someplace and order a book that someone else came up with and give them our money to learn software that the makers don't want to give us. IE http://www.packtpub....ower-board/book

Just wanted to add, as someone who bought that book linked above, it is not going to help you much because it is referring to the 2.0 version of IPB. Most of the things it covers are basic and it doesn't go into that much detail on all the things IPB can do. I did learn the admin interface with it, but if you never worked with 2.0 and are starting IPB with 3.0, I would not bother getting that book.

I do think that when I was a first time user, I did have trouble finding the documentation for the products, but that wasn't because it wasn't provided, it was just newbie-ness. This was back when there were two sites, ipsbeyond (I think it was) and the company site, which added to my confusion. In its current status, it seems to be very easy to find the information. I hadn't checked the new knowledge base until I saw this article...I just learned a couple of things I had questions about :D

Just wanted to add, as someone who bought that book linked above, it is not going to help you much because it is referring to the 2.0 version of IPB. Most of the things it covers are basic and it doesn't go into that much detail on all the things IPB can do. I did learn the admin interface with it, but if you never worked with 2.0 and are starting IPB with 3.0, I would not bother getting that book.

I do think that when I was a first time user, I did have trouble finding the documentation for the products, but that wasn't because it wasn't provided, it was just newbie-ness. This was back when there were two sites, ipsbeyond (I think it was) and the company site, which added to my confusion. In its current status, it seems to be very easy to find the information. I hadn't checked the new knowledge base until I saw this article...I just learned a couple of things I had questions about :D

The link above was mostly referring that their were be some other book coming out for IP 3.0 sometime and should we buy that or wait for IP to give us more information they what is currently there.

Do you have any details?

As Mark has already said, we try to document every ACP page, and we attempt to document the things that need to be documented (while skipping "click the login button to login" type articles). Have you browsed our documentation yet by chance? If you have, and you feel things are underdocumented, the best bet is to tell us exactly what isn't documented that we need to put up more information on.

"You need more documentation"

That is hard to act on.

"Feature xyz should be better documented because I didn't know I had to go to page qrs to use it"

We can do something about that.

Expand more on what you current have, add more details, back and front end. Again it goes for all the IP product lines not just one.

Expand more on what you current have, add more details, back and front end. Again it goes for all the IP product lines not just one.

You still side-stepped what I was asking.

Expand more on WHICH articles? What isn't clear, or is lacking?

Add more details about WHAT? We obviously feel that what IS documented is documented well enough, so if it isn't, you need to tell us what specific it's missing.

Add more articles about WHAT on the back and front end. Again, we need details here.


We are adding new documentation articles all the time, but if there's something specific you want to see right away, please let us know. Just saying "add more articles" goes back to my original point - that doesn't identify what the articles should be about, or what needs better documenting specifically.

You still side-stepped what I was asking.

Expand more on WHICH articles? What isn't clear, or is lacking?

Add more details about WHAT? We obviously feel that what IS documented is documented well enough, so if it isn't, you need to tell us what specific it's missing.

Add more articles about WHAT on the back and front end. Again, we need details here.

We are adding new documentation articles all the time, but if there's something specific you want to see right away, please let us know. Just saying "add more articles" goes back to my original point - that doesn't identify what the articles should be about, or what needs better documenting specifically.

Sorry for not replying sooner been busy. Side-stepped? I think not, I was speaking on a general level of your articles. There not a specif article that I'm calling into question. In some articles you should help to define items and parts of what your trying to explain. Let expand on this this article. IP.Content Getting Started Guide Here it talks about the IP Content and stuff, off hand it pretty good, but it can be improve upon and expand on more of the interface what it does and specifics of the application as well as more details video. Moving on to a Database article. What the article explains is in the database and what it does. But it should be more expand on what does it do with conjuration with something that is active and how to do it. Step by by step information would help other users that are not up in the knowledge tree with this stuff like you guys that made the software. Examples people can work with on there own system, not the article system that is set up but something that can go through with and really see what can be done and not something that is just put together but something that can really sure the power of what your trying to explain. To the statement of front in, easy the front of the IPS software, new users should have a place to know what they need to do to understand has things work, posting, interact with the the software. Most oft what there in the article section is meant for upper level people who know how to work IPS in and out. There are some novice articles and medium user articles, but when an article is written it should be for all levels and not just one area. So bottom line, when writing an article it should aim to fit to answer question from all three levels and detail more then what has been there so far. Expand more on how articles are written, and ask other people before posting so that changes can be made before going live so that you can't have to redo it again. (Just and idea) I by no mean I'm trying to be a smart-butt on anything so please don't take it as that. I hope I explain myself well, if not I try another way.
Thanks for your time,
Zak

Just wanted to add, as someone who bought that book linked above, it is not going to help you much because it is referring to the 2.0 version of IPB. Most of the things it covers are basic and it doesn't go into that much detail on all the things IPB can do. I did learn the admin interface with it, but if you never worked with 2.0 and are starting IPB with 3.0, I would not bother getting that book.

I do think that when I was a first time user, I did have trouble finding the documentation for the products, but that wasn't because it wasn't provided, it was just newbie-ness. This was back when there were two sites, ipsbeyond (I think it was) and the company site, which added to my confusion. In its current status, it seems to be very easy to find the information. I hadn't checked the new knowledge base until I saw this article...I just learned a couple of things I had questions about :D

The looks of things, may have to buy it. Well when version 3 comes out. lol

Sorry for not replying sooner been busy. Side-stepped? I think not, I was speaking on a general level of your articles. There not a specif article that I'm calling into question. In some articles you should help to define items and parts of what your trying to explain. Let expand on this this article. IP.Content Getting Started Guide Here it talks about the IP Content and stuff, off hand it pretty good, but it can be improve upon and expand on more of the interface what it does and specifics of the application as well as more details video. Moving on to a Database article. What the article explains is in the database and what it does. But it should be more expand on what does it do with conjuration with something that is active and how to do it. Step by by step information would help other users that are not up in the knowledge tree with this stuff like you guys that made the software. Examples people can work with on there own system, not the article system that is set up but something that can go through with and really see what can be done and not something that is just put together but something that can really sure the power of what your trying to explain. To the statement of front in, easy the front of the IPS software, new users should have a place to know what they need to do to understand has things work, posting, interact with the the software. Most oft what there in the article section is meant for upper level people who know how to work IPS in and out. There are some novice articles and medium user articles, but when an article is written it should be for all levels and not just one area. So bottom line, when writing an article it should aim to fit to answer question from all three levels and detail more then what has been there so far. Expand more on how articles are written, and ask other people before posting so that changes can be made before going live so that you can't have to redo it again. (Just and idea) I by no mean I'm trying to be a smart-butt on anything so please don't take it as that. I hope I explain myself well, if not I try another way.

Thanks for your time,

Zak

No, I know you're not trying to be a smart-alec (and neither am I). We just want to get on the same page so I know WHAT needs to be updated. This post has specifics, which is more helpful than the posts you made previously where I was asking for specifics.

The getting started article was probably not the best example to expand upon. Really, it's intention was to give a *brief* overview of everything to get people started (hence the title), not so much an in-detail article of all features in IP.Content.

What we did to compensate was write a separate article for each major area to cover it in more detail. Getting started helps get you going, but then if you need more details we have these

• Blocks
• Pages
• Media Manager
• Databases
• Pages (and page management)
  

Is there information that needs to be expanded upon in those articles? Or is it just too techy? I wrote most of these articles, and admittedly I'm not an average "end user".

One thing to keep in mind as well - if any articles need to be expanded upon, aren't clear, or are missing important information, just add a comment to the specific article. Mark goes through all the comments and updates articles to incorporate feedback. :)


For the databases, what we did was write a *separate* article that shows how to "create and use" a database (which is what it sounds like you're after). It can be found here. It describes how we created our Links database, shows the template code we used, and the configuration we used.


As I said before, add comments to any existing articles that need to be updated, clarified, expanded upon, etc. We do go through those and update the articles appropriately. If no one does this, however, we don't know what needs to be updated and expanded upon.

Alright then I keep and eye out and add stuff to keep you and Mark even more busy! ;)

Anything to keep Mark busier is fine with me. :P :whistle:

The looks of things, may have to buy it. Well when version 3 comes out. lol

Really I wouldn't waste the money on it even if there's going to be a version 3. It'll probably cover things you already know right now or things that already in the Knowledge Base.
The book really did not cover the components of IPB so it probably wouldn't cover IP Content either.

In any case, looks like providing feedback on the articles here is enough to get some updates and changes. :D

Anything to keep Mark busier is fine with me. :P :whistle:

>_<

Really I wouldn't waste the money on it even if there's going to be a version 3. It'll probably cover things you already know right now or things that already in the Knowledge Base.

The book really did not cover the components of IPB so it probably wouldn't cover IP Content either.

In any case, looks like providing feedback on the articles here is enough to get some updates and changes. :D

I do work on documentation roughly every other day - if someone says "Hey I want this done" I will do it ;) That's what those comments on the articles are for, and I'll bet you didn't know if you search for something and it returns no results, it logs what you searched for ;)

It's just when people say "documentation needs to be better".... I don't know what they want. If I could read minds, I'd probably be in a different job :P

I have bought IPB 3 and been testing and customizing it for a month now and I'm ready to deploy it to prod. I too, have some suggestions in terms of documentation. From a developer's perspective I'd like to see two specific areas to be improved:

1. The Single Sign On capability. IP board does have a SSO plugin itself, plus the IP converge product. When I first started, they are somewhat confusing and it took a while for me to figure out they are different and how to use them. Some documentation on SSO that covers both and with examples on how to use them will be great.

2. API docs. IPB board has some powerful APIs but I often found myself look into scripts like core.php to figure out how to use them. The current doc is a bit lacking. Also, for XML-API, I wasn't able to find anything to explain the format of XML that needs to be sent to the board backend. Some code sample will be wonderful.

I really feel there are some brilliant minds behind the development of IP broad products. I think good documentation can definitely makes a great product even better.

Hello,

1)
IP.Converge: http://community.invisionpower.com/resources/official.html?record=6
SSO API's: http://community.invisionpower.com/resources/official.html?record=130
Custom login modules: http://community.invisionpower.com/resources/official.html?record=123
More on SSO: http://community.invisionpower.com/resources/official.html?record=9
Other login related articles: http://community.invisionpower.com/resources/official.html?category=41

What is it that isn't explained in the above articles that you would like to see clarified?

2) XML-RPC api is a bit underdocumented, primarily because so few people use it. Code examples would be useful, I agree.
phpdocs were posted today: http://community.invisionpower.com/resources/phpdocs/index.html

Hello,

1)

IP.Converge: [url="http://community.invisionpower.com/resources/official.html?record=6"]http://community.inv...l.html?record=6[/url]

SSO API's: [url="http://community.invisionpower.com/resources/official.html?record=130"]http://community.inv...html?record=130[/url]

Custom login modules: [url="http://community.invisionpower.com/resources/official.html?record=123"]http://community.inv...html?record=123[/url]

More on SSO: [url="http://community.invisionpower.com/resources/official.html?record=9"]http://community.inv...l.html?record=9[/url]

Other login related articles: [url="http://community.invisionpower.com/resources/official.html?category=41"]http://community.inv...tml?category=41[/url]

What is it that isn't explained in the above articles that you would like to see clarified?

2) XML-RPC api is a bit underdocumented, primarily because so few people use it. Code examples would be useful, I agree.

phpdocs were posted today: [url="http://community.invisionpower.com/resources/phpdocs/index.html"]http://community.inv...docs/index.html[/url]

[url="

[/url]

just a side note bfarber cus your in bed by now but you lot forgot dev articles on adding bits to the UCP. Or i can't find them.

2) XML-RPC api is a bit underdocumented, primarily because so few people use it. Code examples would be useful, I agree.

I was trying to use it, but could not figure out how to... perhaps if it was better documented, more people would use it. :thumbsup:

Thanks for all the docs posted today. I will give them a read in a bit.

Do you have any details?

As Mark has already said, we try to document every ACP page, and we attempt to document the things that need to be documented (while skipping "click the login button to login" type articles). Have you browsed our documentation yet by chance? If you have, and you feel things are underdocumented, the best bet is to tell us exactly what isn't documented that we need to put up more information on.

"You need more documentation"

That is hard to act on.

"Feature xyz should be better documented because I didn't know I had to go to page qrs to use it"

We can do something about that.

From what I've seen a potential Customer there has been several requests like this. Even if it simply stupid things they should be there just in case.

And I don't think people expect you to make the support documents int a help document but possible a wiki style might be helpful.

In general I think its important to remember these are help documents and they hsould be written for a complete novice. Becasue potential new customers or new forum owners will need more hand holding.