Documentation?

[Tom Whiting]

Well, let's hope this one goes a bit better than my last topic, which (seriously) wasn't meant to turn out as a flame war, or start one, but express my concern over what I felt to be a poor support timeframe.

Anyways, it's always good to have full product documentation, somewhere, yet, the links (in the admincp itself) go to support/docs/getting_started/board_gsg.php (on the IPB site) which doesn't exist. Oversight? Maybe the manual's not done yet?

Checking the 'support' dropdown, I see FAQS (which don't cover everything), in the client area, I see a link to a 'knowledge base' which, again, like the FAQS don't cover everything @ all (and it shouldn't).

Maybe I'm missing something here, or maybe the manual for 3.x isn't ready yet?

[uberjon]

i would tend to agree with the last part of your post, "manual/doc for 3.x isn't ready yet"

honestly though. with such a complete rewrite and a pwnage one at that... its probably going to take some time before even basic documentation is fully written, let alone advanced feature data, and then finally skinning and hooks etc...

i would like to express personally my hope that "damn good documentation" comes within a reasonable time frame. i know SMF 2.0.x series that is in the works, has little documentation. (if i recall, they are actually looking for more people to assist with it.)

i could actually see IPB going to the extremes of hiring an entire "team" dedicated to just manuals/faqs/guides/documentation/etc... as in my opinion it is KEY to sucess for a "set and forget forum" and a "tweak and mod to the max" forum.

the more data the community has at hand, the better in the long run. especially to create a strong active mod/skin community!

but enoug of my opinions. to the point.. (i hope) IPS has worked so hard to get IPB3 out, that the product is ahead of the manual so to speak. (or so im assuming)

[CalendarOfUpdates]

Here are a few that may help you http://resources.invisionpower.com/index.php?appcomponent=cms&module=articles&category=134 and http://community.invisionpower.com/topic/292645-creating-an-application-documentation/

That is a start anyway.

[pisaldi]

[quote name='Tom Whiting' date='19 September 2009 - 02:18 PM' timestamp='1253362720' post='1857350']
Maybe I'm missing something here, or maybe the manual for 3.x isn't ready yet?


Now, it is only a dream that nobody knows when will convert into reality... perhaps in Christmas...
:whistle:

[Mark]

In 2.3 we had this massive pdf file which you could download and was "the manual". But we learnt this wasn't all that great, it was hard to update, took forever to write, and most of it was filled with stuff like "to add a forum, click 'add forum'".


So for 3.0, we're not planning on having one of those again. The way we see it, there are three very different types of documentation needed:

Firstly, there's the "How to...?" type of documentation - this includes like how to add a forum, set up Facebook Connect etc (so basically, the bulk of what we would consider documentation). We deliver this sort of stuff inline the Admin CP. From any page, click "Get Help With This Page" to reveal a tutorial (if there isn't a tutorial for that page, we make a log of your request and will add to them as time goes on).
If you're not sure how to get to the page you want, you can use the "live search" function in the Admin CP.

Next there's the "known issues" - this includes how to overcome particular error messages or known problems with certain hosts. We deliver this through the knowledgebase in the client area (you'll note when you submit a ticket, it shows you any knowledgebase articles that might be useful).
We're planning to archive all of the 2.x articles in there a little down the road (i.e. once most people are on 3.0) to make it a bit more organised.

Finally there's the "guides". We know certain things cannot be explained just in one Admin CP help page - for starters, we'll need a guide that tells people how to use the live search and "Get Help With This Page" button - we also need things like installation guide, moderation guide, developer documentation and skinning guides.
At the moment, these are a bit scattered - the install guide is in the download package, and a lot the other stuff is on our resource site in the "Articles" section. At the moment, we're focusing on pulling all of these into one location on our main website (which will be that support/docs/ page you found) and putting together the ones we consider top priority (i.e. "Getting Started" and "Moderation") - this will all be done soon.


Hope that clears things up a bit :)

[Tom Whiting]

So, what you're saying is that there will be no documentation here, except for a few things?

I understand the complexity of updating a PDF, but there are other ways to build the same manual, and , honestly, from the advanced user's side of things, a "guide" won't cover much, if anything.

For example, variables, what can and can't be used where? In a "guide", not really practical, but in a full blown, documentation type manual, practical.

[Mark]

What you're looking for sounds like developer documentation - which is quite different to user documentation.

For developer documentation - there's this for creating an application: http://community.invisionpower.com/topic/292645-creating-an-application-documentation/
Along with all of this: http://resources.invisionpower.com/index.php?appcomponent=cms&module=articles&category=135

[bfarber]

[quote name='Tom Whiting' date='19 September 2009 - 06:08 PM' timestamp='1253398117' post='1857460']
For example, variables, what can and can't be used where? In a "guide", not really practical, but in a full blown, documentation type manual, practical.


For the record, we had no description of the variables used throughout IPB in the giant PDF we used to have either.

[Tom Whiting]

So, basically, developers are left to help themselves. Nice one. Ignore the people that extend your product and functionality.

And no, that's not the only documentation I was looking for. A "getting started guide" doesn't cover everything though, and barely covers the "getting started", from one person (or group of person's) perspective, which doesn't help much. Sure, it helps a person get 'started' using your product, but what after that? What about when a user wants to change a theme? Of course, there's no 'documentation' for that.

You need real documentation, not just a guide to how to get started from a few people's perspectives. I get that the product is 'new', but you need at least the basic product documentation and howtos up before you release this stuff. Otherwise, you end up dealing with customers that have no idea what's gong on, all because you couldn't write documentation beforehand.

[bfarber]

Developers are not left to themselves. In fact, we have more developer documentation at this time than anything else. :blink:

http://resources.invisionpower.com/index.php?appcomponent=cms&module=articles&category=135

[Tom Whiting]

[quote name='bfarber' date='21 September 2009 - 09:41 AM' timestamp='1253544082' post='1857841']
Developers are not left to themselves. In fact, we have more developer documentation at this time than anything else. :blink:


That is not documentation by any means.
Documentation helps the user understand what they're doing (and yes, even developers need that at times), not simply throwing them into code.
Documentation belongs in a manual, well written, well thought out, well presented, not spread out over 50 different articles.
In addition, it's on the company to provide documentation, not the end user.
Articles are opinion based and wordy, documentation is not.

You want to see proper, broken down documentation? Look at your competition. THEY did it right, and they've managed to keep it updated well enough. Examples, and explanation of what should be done, not just random code left for the user to figure out for themselves. Not to mention they've managed to keep it up to date. Easy to read, very well outlined, easy to follow manual.

[Lockjit]

I have to agree with the OP here... Everything in life comes with a set of instructions, IPB should be no different.

If you educate people properly about your product then you should reduce some of the strain on your support system, you will also reduce the amount of frustrated customers who post there questions here and never get a reply. If you put the hard work in at the start, it will pay off in the future giving you more resources to build more products to make more money... see where i'm going here?

To use the excuse "we have more developer documentation at this time than anything else." is just lame IMO. It goes to show that you didn't do the job properly first time round.

[Tom Whiting]

[quote name='Lockjit' date='21 September 2009 - 10:56 AM' timestamp='1253548565' post='1857863']
If you educate people properly about your product then you should reduce some of the strain on your support system, you will also reduce the amount of frustrated customers who post there questions here and never get a reply.

Exactly!

[Keith J Kacin]

While I agree documentation is important, I feel the integrated help they have is useful. If you are on a certain page of your Admin CP and you want to know what something does, the help for it should be right there in front of you. That is how it is currently.

Developer documentation is a completely separate thing.

[Tom Whiting]

[quote name='K. J. K.' date='21 September 2009 - 11:06 AM' timestamp='1253549199' post='1857866']
While I agree documentation is important, I feel the integrated help they have is useful. If you are on a certain page of your Admin CP and you want to know what something does, the help for it should be right there in front of you. That is how it is currently.

That 'right there in front of you' doesn't actually tell you how to change a setting, such as, say, how to disable certain login requirements (capcha, etc), or how to change the site's default theme, and it shouldn't. While it's good to have what's there there, it's not that helpful. THAT is why you need a manual. NOT a 'getting started guide', NOT a help screen @ the top of the page


[quote name='K. J. K.' date='21 September 2009 - 11:06 AM' timestamp='1253549199' post='1857866']
Developer documentation is a completely separate thing.

And is only part of why this thread was created. In fact, that is only a minor part of what I've spent the last week looking for.

Full documentation is the solution to everything here. Sure, developer documentation should be a 'minor' part of this (and, again, not code examples, but actual documentation of what is there), but it's still important to have at least the basics covered.

[Keith J Kacin]

[quote name='Tom Whiting' date='21 September 2009 - 11:14 AM' timestamp='1253549677' post='1857868']
That 'right there in front of you' doesn't actually tell you how to change a setting, such as, say, how to disable certain login requirements (capcha, etc), or how to change the site's default theme, and it shouldn't. While it's good to have what's there there, it's not that helpful. THAT is why you need a manual. NOT a 'getting started guide', NOT a help screen @ the top of the page



To be fair, I have no viewed an IPB Admin CP since early 3.0 betas. I'm not sure what was added/removed in terms of the help. So I cannot vouch for what is in the help text, but I believe the idea behind it is a good one.

[Tom Whiting]

[quote name='K. J. K.' date='21 September 2009 - 11:18 AM' timestamp='1253549888' post='1857870']
I believe the idea behind it is a good one.

Absolutely! For small stuff, you're right, it's an ingenious idea. However, that doesn't remove the need for an all out manual.

[rct2·com]

If I were a director of InVision, with the well documented turmoil going on at vbulletin, and a tranche of new versions of stuff here, plus some brand new products, some good strong user documentation would be right near the TOP of my list of things to do,to make it (as far as possible) a 'no brainer' decision to both buy the product if I didn't have a board, and to transfer over to it, if I didn't.

I say that even though I have been very public in my discontent about the lack of support in general (not just documentation) for developers. I think a user manual would be a priority.

[bfarber]

[quote name='rct2dotcom' date='22 September 2009 - 07:46 AM' timestamp='1253619991' post='1860255']
If I were a director of InVision, with the well documented turmoil going on at vbulletin, and a tranche of new versions of stuff here, plus some brand new products, some good strong user documentation would be right near the TOP of my list of things to do,to make it (as far as possible) a 'no brainer' decision to both buy the product if I didn't have a board, and to transfer over to it, if I didn't.

I say that even though I have been very public in my discontent about the lack of support in general (not just documentation) for developers. I think a user manual would be a priority.


It is a top priority. Documentation doesn't write itself, and our product is so large it can't be documented over night. But it's one of the top items on our internal to-do lists, and I believe this has been stated multiple times now across the forums.

[Tom Whiting]

[quote name='bfarber' date='22 September 2009 - 08:39 AM' timestamp='1253626797' post='1860274']
It is a top priority. Documentation doesn't write itself, and our product is so large it can't be documented over night. But it's one of the top items on our internal to-do lists, and I believe this has been stated multiple times now across the forums.


While I sympathize with your position, this line really doesn't work.
Sure, documentation doesn't "write itself", but then again, neither does code. As this stuff is written, it should be documented, not as an afterthought.

[quote name='Mark' date='19 September 2009 - 05:00 PM' timestamp='1253397624' post='1857459']
So for 3.0, we're not planning on having one of those again.


so, which is it? Will there be a manual, or will there not be a manual? Please, do clarify.

The types of documentation described previously work somewhat well (though articles are not documentation by any means) for new users, yet these do not relieve the need for a manual of some kind.

Getting started guides, great idea, and could easily be a 'chapter' in the manual, but definitely don't take the place of it.
Inline help, as well, great idea, but this doesn't cover everything at all, and it shouldn't.
Articles, too wordy and opinion based, definitely not documentation.

There needs to be some sort of manual here, which, as already said before (not by me, mind you) would cut down on needs for support , and promote some sort of customer satisfaction. Somewhere a customer can go and say "ahah, THIS is how I do this", whether it's an advanced customer wanting to learn how to change a theme, or a new customer just wanting a step by step guide to creating a new forum. Both of those are just examples, but you still have a major need for documentation here , because the product obviously does not document itself.

[Mark]

[quote name='Tom Whiting' date='22 September 2009 - 03:48 PM' timestamp='1253630887' post='1860290']
so, which is it? Will there be a manual, or will there not be a manual? Please, do clarify.

The types of documentation described previously work somewhat well (though articles are not documentation by any means) for new users, yet these do not relieve the need for a manual of some kind.

Getting started guides, great idea, and could easily be a 'chapter' in the manual, but definitely don't take the place of it.
Inline help, as well, great idea, but this doesn't cover everything at all, and it shouldn't.
Articles, too wordy and opinion based, definitely not documentation.

There needs to be some sort of manual here, which, as already said before (not by me, mind you) would cut down on needs for support, and promote some sort of customer satisfaction. Somewhere a customer can go and say "ahah, THIS is how I do this", whether it's an advanced customer wanting to learn how to change a theme, or a new customer just wanting a step by step guide to creating a new forum. Both of those are just examples, but you still have a major need for documentation here , because the product obviously does not document itself.


There will not be a single manual. Our users told us it was hard to find what they were looking for, and we found it hard to update. Having one in addition to the other resources we have available would result in duplicate content.

We will continue to expand on the inline help and knowledgebase, and will be releasing our additional walkthrough-type guides soon.

As said many times - the main documentation source is the inline help, additional guides will be supporting that inline help where a particular process either spans many areas of the software or is particularly complicated and examples are needed. Everything that was in the 2.3 manual will be available - 80% of it already is.


While I appreciate that you find a manual would be very helpful, the vast majority of customers I have spoken to find the new system much easier, and it has cut benefited out support department.

I think the fact of the matter is that we cannot please everyone: some users would prefer a large pdf that they can read the whole way through - others prefer inline help that easy to locate a specific article and always up to date. We can't have both, it's just not feasible - we have to go with one and we have gone with the new system.


As always, thank you for voicing your feedback and let us know if you have any other suggestions :)

[Tom Whiting]

I think the fact of the matter is that we cannot please everyone: some users would prefer a large pdf that they can read the whole way through - others prefer inline help that easy to locate a specific article and always up to date. We can't have both, it's just not feasible - we have to go with one and we have gone with the new system.
Nobody want's a "large pdf" here, nobody's ASKING for it. You're right, that's just way too much.
If you think a "large pdf" is the ONLY way to do a manual, you're grossly mistaken. Again, look at how your competition does things, properly. Easy to update, not hard to deal with, and it's all right there.
Your "inline help" is severely lacking, and you can not deny that your proposed "solution" to these problems is not even a solution. Guides aren't going to cover much of anything. Inline help really doesn't cover anything, and articles are a joke.

So, what you have here is an astoundingly large piece of software with no proper documentation at all. You leave users hanging, instead of properly documenting your system, and providing information to your customers. Nice way to keep your customers.

Oh, and this is not accurate at all:
We can't have both
Can't means that it is physically impossible to do. This is 100% inaccurate. What IS accurate is

We won't have both
Which means, of course that you will not do it.

There is a huge difference between the two, and choosing that road shows a great disrespect for your customers, new, and old.

[Guest]

[quote name='Tom Whiting' date='22 September 2009 - 05:30 PM' timestamp='1253637056' post='1860314']
Nobody want's a "large pdf" here, nobody's ASKING for it. You're right, that's just way too much.
If you think a "large pdf" is the ONLY way to do a manual, you're grossly mistaken. Again, look at how your competition does things, properly. Easy to update, not hard to deal with, and it's all right there.
Your "inline help" is severely lacking, and you can not deny that your proposed "solution" to these problems is not even a solution. Guides aren't going to cover much of anything. Inline help really doesn't cover anything, and articles are a joke.

So, what you have here is an astoundingly large piece of software with no proper documentation at all. You leave users hanging, instead of properly documenting your system, and providing information to your customers. Nice way to keep your customers.

How about instead of merely saying that what Invision have is lacking, and what the competition has is better... Why not actually be constructive and say what it is that you want? Tell Invision, and the rest of us, in detail, what you consider to be "proper" documentation. What would satisfy your requirements?

Your hand-wavey complaints help no-one, constructive feedback would be much more useful.


Edit: Also, for the sake of being pedantic, as you were, "can't" can mean forbidden to / not permitted to, and thus IPS can not permit themselves to waste time on duplicating documentation. Thus they can't have both. :)

[Mark]

Tom,

We're kind of going round in circles here. I don't know whether it's just that you don't like the new system, or you're having trouble finding what you need.

If there is something in particular that you are having trouble finding documentation on, please let me know and I will either direct you to it or get something written up if it is not available, but continuously making blanket statements of our documentation lacking doesn't help us help you. Tell us what you want, and we will do our best to provide.

If it's just that you don't like the idea of inline help and would prefer a single manual, then I'm sorry to hear that, but it's what the majority of our customers asked for.

[KT Walrus]

Maybe IPS could write a Wiki app (or forums module) and let us users and IPS staff write the documentation online here. Wikis are much better than having an articles forum as everyone can edit the content.