Documentation?

[CalendarOfUpdates]

[quote name='KT Walrus' date='22 September 2009 - 03:25 PM' timestamp='1253647559' post='1860358']
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.

They already do. http://community.invisionpower.com/page/articles.html

[.Ian]

hardly the same thing ;) A wiki would be good.

[bfarber]

[quote name='Tom Whiting' date='22 September 2009 - 10:48 AM' timestamp='1253630887' post='1860290']
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.


As we are writing code, we do not take breaks to write documentation of the code just written. I'd be impressed to find any developers that actually document (externally) each line of code as they are writing it, properly.

Firstly, developers are not the best people to document a product. They look at the product from a development perspective, tend to speak techie lingo, and generally aren't good at identifying issues to common users that need to be documented.

If you are talking about code-level documentation, we use phpdoc comments entirely throughout IPB - feel free to extract them. We will be putting phpdocs online at some point, so if all of your complaints resolve around this, then it will be addressed in the near future. I gather, though, from most of your statements, that this isn't going to satisfy your requests.

[quote name='Tom Whiting' date='22 September 2009 - 10:48 AM' timestamp='1253630887' post='1860290']
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.


You are missing the simple "WHY" in all of this. WHY does there need to be a manual? Because out of several available means of documentation (inline help, getting started guides, our knowledgebase, articles on the resource site, the phpdoc I already mentioned will be going online for developers in the future) you think a manual is better? This is opinion. :)

[quote name='Tom Whiting' date='22 September 2009 - 12: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.

For a product our size, if you want an actual "manual" I don't see how it wouldn't be large. The 2.3 PDF file was 160 pages, for instance.

[quote name='Tom Whiting' date='22 September 2009 - 12:30 PM' timestamp='1253637056' post='1860314']
Again, look at how your competition does things, properly. Easy to update, not hard to deal with, and it's all right there.

I'll bite. If you give me a link to this documentation you're talking about, I'll take a look so we can compare apples to apples. Frankly, though, I don't spend my days browsing through our various competitor's websites.

[quote name='Tom Whiting' date='22 September 2009 - 12:30 PM' timestamp='1253637056' post='1860314']
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.


Again, all opinions. :) Inline help is new and will grow over time, but already it covers a large majority of things that customers inquire about. You simply have to use it. Guides WILL cover a number of scenarios. "How do I set up a new moderator" for instance. Why are articles a joke? Because you don't want to use them, or because you haven't found one you thought answered a specific inquiry you had? Many of our customers do find the articles very useful. There's a lot of useful how-to's, general information, developer-oriented code examples, and simple modifications in the articles area.

[quote name='isdoo' date='22 September 2009 - 04:00 PM' timestamp='1253649653' post='1860363']
hardly the same thing ;) A wiki would be good.


How? Any user can edit any article. There are revisions and so on. It is in fact a wiki. ;)

[pisaldi]

[quote name='Mark' date='22 September 2009 - 06:19 PM' timestamp='1253636345' post='1860312']
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 have seen several messages claiming for manuals... manuals for developer, introduction manuals, whole manual...

Why don't you make a public poll to customers about the need of the manual ???



[quote name='bfarber' date='22 September 2009 - 10:24 PM' timestamp='1253651055' post='1860370']
Again, all opinions. :) Inline help is new and will grow over time, but already it covers a large majority of things that customers inquire about. You simply have to use it. Guides WILL cover a number of scenarios. "How do I set up a new moderator" for instance. Why are articles a joke? Because you don't want to use them, or because you haven't found one you thought answered a specific inquiry you had? Many of our customers do find the articles very useful. There's a lot of useful how-to's, general information, developer-oriented code examples, and simple modifications in the articles area.


I'm with the leaders... I'm with Invision... and it is not logical that the leaders can't offer a manual to their customers... you must offer all needed in a software program to your customers, and a manual it is a need...

Inline help is one kind of manual, but lots of customers continue preferring the classical PDF manual that should be printed or where you can make several searches...

:rolleyes:

[.Ian]

BTW - when you do edit an article the code is mucked up goes to

<!--c1--><div class='codetop'></div><div class='codemain'><!--ec1--><a href='<if test="ruleslink:|:$this->settings['gl_link']"><!--c2--></div><!--ec2-->


Personally being totally new to IPB, I struggle at time - I often have the inline help open in the ACP, but more often than not, there is no entry.

For example I would like to use IP.Content - but honestly do not know where to start.

Searching is not wonderful on here - but I do tend to use this if I have a query - then will make a post if I do not understand something - whether I get a reply is another matter.

So if there is no documentation and I can't find it here and no one responds to a post - I am stuffed.

It isn't an error, so I can't out in a ticket really (am sure the tech guys do not wish to answer questions - they are there to fix errors)

So I do not care whether it is a wiki, manual, pdf, help file, stone tablet, smoke signals - as long as it gives the answer and is findable then it doesn't matter (searches on here for many common phrases in IPB are pointless as they have been repeated so often or are under 4 characters)

The other issue with anything on here is that IPB 2.x and IPB 3.x are combined so one cannot search purely for IPB3.x :( And the 20 second timeout - just searched for 'upload' for example in resources and got nothing - so one has to wait another 20 seconds to search for another word. Not ideal for a support lookup.

Just my 2p's worth ;)

[Charles]

I think this topic has devolved into a debate on the various ways one can document software products :) let's not start a huge argument about the merits of one over the other. We all agree documentation is very important and it is being actively worked on.

As IPB3 is so new we are still writing many of these documents. Anyone who has written documentation knows it is extremely time consuming. We actually have quite a bit written already in various areas that has been written over time and as things come up. We are currently working on pulling all that various information together into centralized guides. You may have noticed the new Resources area on our community here and the new capabilities of IP.Content 1.1 - we will be using those new features for our core documentation.

We have, basically, two approaches:

ACP Inline Help: This talks about the specific page you're on without having to leave the admin area. It's not to explain in great detail just to explain the overall functions of the page you're on.
Guides: A traditional article on various subjects.

The guides will have various subjects and take information beyond what the straightforward ACP Inline Help can provide. Examples may include:
[*]Basics of skinning [*]Moderation guide [*]Creation applications/hooks [*]Creating a single-sign-on bridge between IPB and your applications [*]Template logic [*]etc.

Much of this is already written in the form of articles on the resource site and the many dozens of PDFs our development and support departments have written since the launch of IPB3. I am personally organizing all this varied information this week into a logical approach (quite an undertaking I might add). We will begin publishing these various documents in the next few days and continuing to expand upon them quite frequently over the next couple months.

Documentation is very important to us as it is to you. Taken another way, good documents reduce the number of tickets we receive which is good for both our clients and for us. Plus, it eliminates the need for topics like this which end up going in circles with people who, at a base level, do agree with each other. :)

[.Ian]

I think that is the page linked from the forums - http://www.invisionpower.com/support/docs/getting_started/board_gsg.php actually went somewhere then it might help.

Even the info you had up there 3 or 4 weeks ago would be good - even if it not finished as partial info is better than a dead end.

[bfarber]

[quote name='isdoo' date='22 September 2009 - 05:04 PM' timestamp='1253653491' post='1860381']
BTW - when you do edit an article the code is mucked up goes to

<!--c1--><div class='codetop'></div><div class='codemain'><!--ec1--><a href='<if test="ruleslink:|:$this->settings['gl_link']"><!--c2--></div><!--ec2-->



This is a side effect from transferring the data from the previous system to the new system. I will likely try to work out a way to "fix" this, but can't make any promises just yet. It's not an easy task and there's a lot going on atm already.

[Tom Whiting]

[quote name='Dan C' date='22 September 2009 - 02:12 PM' timestamp='1253646763' post='1860354']
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?

I have, multiple times. How many times do I have to say it? Look at the competition, look at their documentation, that is a perfect example of a well written, proper documentation manual, and it's not hard to keep up to date. It's a win/win situation.



[quote name='Mark' date='22 September 2009 - 02:17 PM' timestamp='1253647074' post='1860355']
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.

I'm not going to continue to log helpdesk request after helpdesk request with garbage such as "how do I do this". That wastes MY time and your time.
Inline help does not do that, yet, and it shouldn't ever.
A "quick start guide" doesn't do that now and shouldn't ever do that
Articles are entirely too wordy for that, and entirely too opinion based.
A flat out manual, properly indexed, properly updated would resolve this.

Since IPB doesn't want to do this (will not) , there's really no further need for discussion. I'm sorry that you can't see the need for it, but that's your problem not mine.
When it comes down to it, the excuses from IPS and IPB have turned me away from the product itself. As I stated in my blog, I'm thankful it was only a $20 investment, because it certainly was a loss, but I'm not going to continue to waste my time trying to figure out where things are at, or how to do this, all because someone doesn't want to write proper documentation.

[Guest]

[quote name='Tom Whiting' date='22 September 2009 - 10:59 PM' timestamp='1253656743' post='1860397']
I have, multiple times. How many times do I have to say it? Look at the competition, look at their documentation, that is a perfect example of a well written, proper documentation manual, and it's not hard to keep up to date. It's a win/win situation.

Which competition??? There's many forum softwares out there.

[Carl M]

[quote name='Dan C' date='22 September 2009 - 11:03 PM' timestamp='1253657028' post='1860399']
Which competition??? There's many forum softwares out there.


I guess ones that have documentation for its software. ;)

[Enkidu]

I think IP should start thinking of wiki based documentation where we as a community can co-author the contents and share our experiences etc etc etc
but that's just me :)

[Tom Whiting]

[quote name='Enkidu' date='22 September 2009 - 05:53 PM' timestamp='1253660014' post='1860410']
I think IP should start thinking of wiki based documentation where we as a community can co-author the contents and share our experiences etc etc etc
but that's just me :)


The only problem with that is, just like articles, it gets too wordy and opinion based.
A manual is something that should be developed by a company, not a community, with the quickest and easiest explanation to using the product . A wiki is just the opposite.

[Enkidu]

[quote name='Tom Whiting' date='22 September 2009 - 11:59 PM' timestamp='1253660369' post='1860412']
The only problem with that is, just like articles, it gets too wordy and opinion based.
A manual is something that should be developed by a company, not a community, with the quickest and easiest explanation to using the product . A wiki is just the opposite.


are you asking for a video based tutorials with big red arrows pointing to a setting along with a voice of a sexy lady? :D
when I said wiki, it's just because: everyone has one. wikis are the perfect media for geographically distributed people who work on a common project, they are easy to update, organize, search, and proven to be successful over and over again :)

[stoo2000]

Can I make a feature request?

Can we have the ability to ban Bold bbcode for certain users?

And for the record, Articles are a fantastic way for other users to help users, I have re-written a couple of articles myself in the developer section, adding more useful information as I come across it.

[Tom Whiting]

[quote name='stoo2000' date='22 September 2009 - 06:17 PM' timestamp='1253661441' post='1860415']
And for the record, Articles are a fantastic way for other users to help users, I have re-written a couple of articles myself in the developer section, adding more useful information as I come across it.

Articles are not a "fantastic way to provide documentation". They are longwinded, opinionated and biased. Of course YOU think they're "fantastic", you're biased, you write them, or rewrite them.

ANY software I pick up, anywhere has a manual, except, well, of course IPB, which, I guess is just too good for proper manuals and documentation.

Games? There's a manual telling me what button does what and where, giving me an introduction to the game itself.
php software? A manual, telling me how to do something, clearly and concisely.
OS ? There's a manual right there.

The point is that this software is entirely too complicated to release without a manual. Sure, the "tips" are great, and the "getting started guide" idea might be great, but the articles do NOT replace the need for a manual, they are wordy, poorly written, and only cover things from one person's perspective.

Take my case, for example. I've been using internet software for years, administrating servers for a bit longer. I'm certainly no dummy when it comes to software, yet when I can't for the LIFE of me figure out certain things, I go looking for documentation. NOT documentation that is written by an end user and wordy, but an official product manual. If I, an experienced user is tempted on day 2 to just call it quits because of a poorly documented piece of software, think of what the average newbie is going to do, and how much FASTER they will. Thankfully, I held out for a week, but, in the end, my time is too precious to spend trying to read wordy articles to figure things out.

[Mat Barrie]

You know Tom, I don't know where this mythical documentation for every product in existence you refer to is. You refer to every product you have including a manual, yet... well, lots of software doesn't. I'll do a quick inventory of a sampling of my start menu now (I'll include the OS itself even). I'm excluding "F1 Help" since that's essentially inline help.

Microsoft Windows - No Manual.
Google Chrome - No Manual.
Microsoft Office - No Manual.
Microsoft Visual Studio - No Manual.
MYOB Accounting - Quick Start Guide.
Beyond Compare - No Manual.
Apple iTunes - No Manual.
Kayako SupportSuite - Manual Available!
Microsoft SQL Server - No Manual.
Seapine Surround SCM/Testtrack Pro - Manual Installed!
Stardock Multiplicity - No Manual.

As you can see, lots of stuff with no manual. And you're also completely ignoring what they've said many times - that the majority of their customers prefer articles, guides, inline help, etc over the three hundred page book they printed last time. It doesn't make commercial sense to write an entire manual for three people.

[Tom Whiting]

It doesn't make commercial sense to write an entire manual for three people.
Yeah, there's only 3 people that would look at the thing, right.
Again, nobody is talking about a 300 page manual here, and nobody is talking about having to print the thing out. A properly indexed, categorized and written manual can be done as a webpage, or countless other ways. Articles are NOT manuals, they are articles, wordy, opinionated, and don't provide a bit of guidance.

As far as your "examples", yes, F1 help IS as close to a manual as you're going to get, but guess what? Even that is properly categorized, appendicized and developed. The user can quite simply search for the right thing, and it's there, which is more than can be said for this product right now.

The point is that the product needs this. It's big enough that there is a problem if you don't tell a user how to do something, not in an "article", but an actual manual. By not having something like this available, it wastes current, and new customer's time, and certainly doesn't promote customer satisfaction in the least.

Sure, if you want to keep the same customers that don't care about proper documentation, don't put out a manual. Doesn't matter to me any more, as I'm already done wasting my time on a poorly documented program.

[ᴡᴅツ]

The Subscription Manager is more of a priority than a documentation consisting of what buttons to click in order to add a forum.

[Mark]

The OP has requested this topic be closed. I would just like to reiterate that if anyone believes anything is missing from our documentation - this can include ACP pages you feel needed articles which do not currently have them, or guides you feel need to be written, then please PM me and I will add it to our list. But we do not intend to release one all-encompassing manual.