Jump to content


Photo

Lack of Documenation is SO Frustrating


  • Please log in to reply
42 replies to this topic

#1 Garrett M.

Garrett M.

    Advanced Member

  • +Clients
  • 475 posts

Posted 24 June 2012 - 05:00 PM

Why does this product have almost no documentation?

Simply removing the IPB Wrapper and trying to include the appropriate JS files makes me hate this product.

I can't find anything that says, in detail, WHAT I'm supposed to include to get basic article editing features and comment posting features working properly.

When is IPS going to fix this?

I tried IP.Content about 1.5 years ago and hated it then. Unfortunately 18 months later, this product still seems incredibly immature and unbelievably frustrating to use, mostly in part because there is no documentation.

I am forced, again, to abandon IP.Content so that I can search for products that simply work better then this one.
  • civ, THL, NewRockRabbit and 1 other like this


#2 Rimi

Rimi

    Strip Me

  • +Clients
  • 6,121 posts

Posted 24 June 2012 - 05:07 PM

Out of curiosity are there any prducts that work like IP.Content and let you remove the wrapper?
  • TaffyCaffy and Marcher Technologies like this

#3 Marcher Technologies

Marcher Technologies

    $life=FALSE;$code=TRUE;$time--;

  • +Clients
  • 11,753 posts

Posted 24 June 2012 - 07:40 PM

Why does this product have almost no documentation?

Simply removing the IPB Wrapper and trying to include the appropriate JS files makes me hate this product.

I can't find anything that says, in detail, WHAT I'm supposed to include to get basic article editing features and comment posting features working properly.

When is IPS going to fix this?

I tried IP.Content about 1.5 years ago and hated it then. Unfortunately 18 months later, this product still seems incredibly immature and unbelievably frustrating to use, mostly in part because there is no documentation.

I am forced, again, to abandon IP.Content so that I can search for products that simply work better then this one.

Nor could I, but it is not their job, nor responsibility, to provide the code base that you choose to throw away when going wrapper-less.
I made something to help ease that(freely available in MP), but there are the facts, you choose when going wrapper-less to throw away that code en whole.
  • TaffyCaffy likes this

#4 Garrett M.

Garrett M.

    Advanced Member

  • +Clients
  • 475 posts

Posted 24 June 2012 - 09:49 PM

Out of curiosity are there any prducts that work like IP.Content and let you remove the wrapper?


That isn't my point, that was an example. And to answer your question, there are dozens of other pieces of software, both free and commercial, that have much better documentation than IP.Content.

IP.Content is supposed to be a framework to allow you to build out an entire website. Something as important as that should be well-documented. There should be a place where I can find 90% of my answers, and the last 10% (usually the very-obscure problems) would be helped out by IPS support or the community.

The documentation doesn't have to tell me HOW to build my site, I realize that's my problem. But I should be able to find an up-to-date article on what I'm supposed to include in the header to allow all of the built-in features of IP.Content (adding/editing records, etc.) to continue to work without the wrapper. It's just good development practice.

It frustrates me because I know a lot of people are shying away from IP.Content because of its general lack of ease-of-use. You basically have to be a PHP developer with at least an intermediate understanding of both PHP and IP.Core/IP.Board's framework to do anything advanced with IP.Content.

Nor could I, but it is not their job, nor responsibility, to provide the code base that you choose to throw away when going wrapper-less.


That's not entirely correct. The software gives me the option to remove the wrapper from the page. It simply makes sense that they document what needs to be manually included again so that IP.Content's built-in features continue to work as designed.

I'm well aware that everything else related to design and structure is up to me.
  • AlexJ, NewRockRabbit, Weppa333 and 1 other like this


#5 Rimi

Rimi

    Strip Me

  • +Clients
  • 6,121 posts

Posted 24 June 2012 - 10:09 PM

Well I wasn't trying to address the point actually..I'm actually looking for an IP.Content alternative because of money constraints. Got any suggestions?

#6 bfarber

bfarber

    RBT-KS

  • IPS Management
  • 28,654 posts

Posted 25 June 2012 - 08:49 AM

You say this is an example documentation you are looking for. Do you have any others?

We can't document something when we don't know that people are looking for it. We rely on clients to tell us if we're missing any specific documentation. There is several documentation articles on the software already, but naturally we won't have though of everything.

http://community.inv...anel/ipcontent/
http://community.inv...orials/content/
http://community.inv...ces/ip-content/
Community Articles: http://community.inv...ml/_/ipcontent/
(This one talks about getting RTE and Flash working when not using the IPB wrapper, for instance: http://community.inv...pb-wrapper-r416 )
(There is another WIP documentation area with articles that have not yet been made public)

Brandon Farber
Development Manager / Senior Support

If it sounds like fun, it's not allowed on the bus!

php5_zce_logo_new.gif     

Invision Power Services, Inc.


#7 ZakRhyno

ZakRhyno

    All da rhino!

  • +Clients
  • 1,900 posts

Posted 25 June 2012 - 11:26 AM

Yes, but they have not been updated Bfarber it was say when 3.0...or was it 3.3 I forget but it was going to be update with images videos but it just plain jane with not much of an update. But I have spoken about this before in other post. One of the staff members was heading up the effect it was a female but she seems to have disappear from the the forms and it still in it current state.
If updating the stuff is so hard why not just outsource it get a better framework layout and make it work for everybody? I don't like VB but they do have a documentation listing that well does work and is friendly to understand Detail example in this link.
  • AlexJ likes this

#8 Rimi

Rimi

    Strip Me

  • +Clients
  • 6,121 posts

Posted 25 June 2012 - 12:19 PM

Brandon can we get an article for ccsFuntions that's just like the IPSMember one?

#9 AlexJ

AlexJ

    Profiler

  • +Clients
  • 2,116 posts

Posted 25 June 2012 - 01:28 PM

My suggestion would be to clean up present documents. Some things are so old and are no more needed.

Even Joomla, Drupal, etc.. have better documentation then IP.Content. I wish few basic things like making front page without wrapper with top navigation bar could be provided for free. Their is one for old IP.Content version but it doesn't work for latest series. It just helps to get newbies like me started. Without Marcher support, I would be doomed.

referral-0105609001340182954.jpg


#10 bfarber

bfarber

    RBT-KS

  • IPS Management
  • 28,654 posts

Posted 25 June 2012 - 07:48 PM

Yes, but they have not been updated Bfarber it was say when 3.0...or was it 3.3 I forget but it was going to be update with images videos but it just plain jane with not much of an update. But I have spoken about this before in other post. One of the staff members was heading up the effect it was a female but she seems to have disappear from the the forms and it still in it current state.
If updating the stuff is so hard why not just outsource it get a better framework layout and make it work for everybody? I don't like VB but they do have a documentation listing that well does work and is friendly to understand Detail example in this link.


That's impressive...considering there are no female staff members.

Charles has begun work on the new documentation section, but there is a lot to cover and IP.Content has not been hit yet. Even then, I'm not positive we'll see video articles on things like "making a wrapperless page template". That's the sort of thing video can't explain.

Brandon can we get an article for ccsFuntions that's just like the IPSMember one?


I'll add a note about it.

My suggestion would be to clean up present documents. Some things are so old and are no more needed.

Even Joomla, Drupal, etc.. have better documentation then IP.Content. I wish few basic things like making front page without wrapper with top navigation bar could be provided for free. Their is one for old IP.Content version but it doesn't work for latest series. It just helps to get newbies like me started. Without Marcher support, I would be doomed.


See, creating a front page template without a wrapper with a top navigation menu bar is not a "basic thing" I'm afraid. That's really the problem. This is a pretty specific customization and even if we showed a basic example of how to do it, it's not necessarily going to cover what an individual is after. This is the difficult part in documenting an application meant to serve as a framework. We can show you how to use the tools (e.g. we have documentation on creating templates, and what various page options mean), but documentation on what you can accomplish with those tools could be worked on forever and still not answer specific questions.
  • Jandar, TaffyCaffy and Marcher Technologies like this

Brandon Farber
Development Manager / Senior Support

If it sounds like fun, it's not allowed on the bus!

php5_zce_logo_new.gif     

Invision Power Services, Inc.


#11 Garrett M.

Garrett M.

    Advanced Member

  • +Clients
  • 475 posts

Posted 26 June 2012 - 02:10 PM

The link you supplied me with fixed ratings and many other things that weren't working on my web page, but it was apparently not enough to fix the error "ipb.textEditor is undefined". I still cannot find documentation on that error anywhere and have no idea what I'm missing in my code.

IP.Content isn't a basic product like Gallery or Downloads, therefore people need to rely on documentation more than other IPS products.

We can show you how to use the tools (e.g. we have documentation on creating templates, and what various page options mean), but documentation on what you can accomplish with those tools could be worked on forever and still not answer specific questions.


That's not what documentation is for. Documentation is there to document features of a product and their behavior. Overly-specific questions can be answered by the community or IPS via support.

In no way would I expect IPS to supply answers to all questions in documentation. What I expect is answers to the "Framework Questions". The documentation now is a complete mess because its very disorganized and very incomplete.

Here's what the "Add Page" document tells me:

To add a new page, click the "Add Page" button, and then choose the page type from the dropdown. If you are unsure which to choose, choose the "Add Page" option.


That's it. It doesn't explain the features that are part of the three-step wizard, or what I'm even doing in "Pages" for that matter other than "Pages will contain your content".

That is an example of awful documentation.

When I look at documentation for other (non-IPS) products, I'm usually greeted with a nicely structured menu that I can either search or drill into by topic, feature, option, etc. to find the answer.

IP.Content's documentation is broken up into three or four different sections, and you can only search each one one-at-a-time. This is unintuitive, and there is no structure beyond one-level categories, either.

Here's what good documentation should look like for IP.Content. Let's pretend the menu below is what I'm greeted with and I'm currently browsing the "Add Page" document.

IP.Content
-Pages
-Creating a Page
-Add Page
-Add CSS File
-Add Javascript File
-Blocks
-Templates

Inside of "Add Page" document:

(Information below has not been audited, it might bet wrong. It's incomplete and only an example)

Description

One of the core features of getting a website working is adding Pages.

By Default, IP.Content includes three sample pages for you

  • index.html
  • media.html
  • articles.html
For more information about what each individual page does by default, click on the page names above.

The following is a list of options you are given during the page creation process

Page Name

You can type the name of the page in this text box.
  • Use page name as page title?
When this box is checked, the text in this box is placed anywhere that {ccs special_tag="page_title"} is put.
  • Show page in quick navigation?
When this box is checked, a link to this page is added to the Quick Navigation feature. For more information on Quick Navigation, click here.

Page URL

A pre-defined URL is shown under this setting with a text box at the end of it. You must enter the URL of the page in order to access it on the front end. Example include: index.html, index.php, page.html, page.php
  • Omit page name in URL
When enabled, the page name will not be required in the full URL

Warning! When the page url is changed to something other than index.html, this option becomes unavailable


This is what IP.Content needs. The fact that the "Omit page name in URL" option just disappears with no explanation is an example of IP.Content's unintuitivity that can be supplemented by well-thought-out documentation. You aren't trying to tell me how to code in HTML, CSS, or PHP, you are simply explaining what each built-in feature does, and the documentation can explain the ramifications of turning certain features on or off, or what behavior might be impacted when certain settings are changed.

It's just good practice to document this way, and it's what so many other commercially available products or frameworks provide.

IP.Content must have this type of documentation, or it will continue to be relegated to the status of "Advanced Portal".
  • AlexJ, vitoreis and NewRockRabbit like this


#12 Marcher Technologies

Marcher Technologies

    $life=FALSE;$code=TRUE;$time--;

  • +Clients
  • 11,753 posts

Posted 26 June 2012 - 02:49 PM

.... ok, first of all.. Advanced Portal is a complete insult to what IPC is.... That is no bloody portal unless you want it to be one, and such is a gross under-use.
Secondly.
<script type='text/javascript' src='{$this->settings['js_base_url']}js/3rd_party/prototype.js'></script>
<!-- ::: OH CKE IS FUN ::: -->
<script type='text/javascript' src='{$this->settings['js_base_url']}js/ipb.js?ipbv={$this->registry->output->antiCacheHash}&amp;load=quickpm,hovercard,sharelinks,rating,like,textEditor,tags,comments'></script>
<script type='text/javascript' src='{$this->settings['js_base_url']}js/3rd_party/scriptaculous/scriptaculous-cache.js'></script>
<script type="text/javascript" src='{$this->settings['cache_dir']}lang_cache/{$this->lang->lang_id}/ipb.lang.js' charset='{$this->settings['gb_char_set']}'></script>
{parse template="liveEditJs" group="global"}
Thirdly, You raise valid points to a one.
Farber, 9 times out of 10 after customs I spend an hour or more simply teaching the Basics to the client, this is where you change x/y/z for a page, this is where you change x/y/z for a database, this is why doing x results in y.

#13 Rimi

Rimi

    Strip Me

  • +Clients
  • 6,121 posts

Posted 26 June 2012 - 03:40 PM

So...I take it there aren't any alternatives after all? <_<

#14 Garrett M.

Garrett M.

    Advanced Member

  • +Clients
  • 475 posts

Posted 26 June 2012 - 04:24 PM

.... ok, first of all.. Advanced Portal is a complete insult to what IPC is.... That is no bloody portal unless you want it to be one, and such is a gross under-use.


I didn't say that's what IPC was, I said that's what it will be relegated to without better documentation. People won't use it if they can't figure it out.

Secondly.

<script type='text/javascript' src='{$this->settings['js_base_url']}js/3rd_party/prototype.js'></script>
<!-- ::: OH CKE IS FUN ::: -->
<script type='text/javascript' src='{$this->settings['js_base_url']}js/ipb.js?ipbv={$this->registry->output->antiCacheHash}&amp;load=quickpm,hovercard,sharelinks,rating,like,textEditor,tags,comments'></script>
<script type='text/javascript' src='{$this->settings['js_base_url']}js/3rd_party/scriptaculous/scriptaculous-cache.js'></script>
<script type="text/javascript" src='{$this->settings['cache_dir']}lang_cache/{$this->lang->lang_id}/ipb.lang.js' charset='{$this->settings['gb_char_set']}'></script>
{parse template="liveEditJs" group="global"}



Thank you. This make all JS errors go away. The last step is figuring out why the CKEditor won't show up at all still. I suspect a configuration issue but will keep looking.


So...I take it there aren't any alternatives after all? <_<


Sorry... I'm not aware of anything that works with IPB the way IP.Content does.
  • NewRockRabbit likes this


#15 Rimi

Rimi

    Strip Me

  • +Clients
  • 6,121 posts

Posted 26 June 2012 - 05:56 PM

Then what were you talking about in the first post?
  • Marcher Technologies likes this

#16 Garrett M.

Garrett M.

    Advanced Member

  • +Clients
  • 475 posts

Posted 26 June 2012 - 08:05 PM

Then what were you talking about in the first post?


There are dozens of other CMS systems that solve many of the problems IP.Content is trying to solve. I was looking at IP.Content because of its incredibly tight integration with IP.Board.

Many others can do what IP.Content can do, sans-forum integration. Off the top of my head:

Orchard Project (Requires Windows Server)
Joomla (PHP-Based, Open Source, Free)
Drupal (PHP-Based, Open Source, Free)
WordPress (PHP-Based, Open Source, Free)
Sitefinity (.NET Based, Commercial, Free Community Edition, otherwise $$$)
DotNetNuke Professional (.NET Based, Commercial, Free Community Edition, otherwise $$)
Umbraco (Not sure of backend type, Free basic edition, a la carte options $$$)

I'm currently evaluating IP.Content and Sitefinity CE.

All of IP.Content's features can be done on other platforms, the system isn't unique.


#17 Marcher Technologies

Marcher Technologies

    $life=FALSE;$code=TRUE;$time--;

  • +Clients
  • 11,753 posts

Posted 26 June 2012 - 08:25 PM

There are dozens of other CMS systems that solve many of the problems IP.Content is trying to solve. I was looking at IP.Content because of its incredibly tight integration with IP.Board.

Many others can do what IP.Content can do, sans-forum integration. Off the top of my head:

Orchard Project (Requires Windows Server)
Joomla (PHP-Based, Open Source, Free)
Drupal (PHP-Based, Open Source, Free)
WordPress (PHP-Based, Open Source, Free)
Sitefinity (.NET Based, Commercial, Free Community Edition, otherwise $$$)
DotNetNuke Professional (.NET Based, Commercial, Free Community Edition, otherwise $$)
Umbraco (Not sure of backend type, Free basic edition, a la carte options $$$)

I'm currently evaluating IP.Content and Sitefinity CE.

All of IP.Content's features can be done on other platforms, the system isn't unique.

And which, pray-tell, of those allow Custom System creation(databases), or what Feed Blocks can do for you without spitting code? the fact you directly compare Content to these as an argument proves you keep missing the data management for the page it is displayed on.
You treat and use Content as an Over-glorified portal, therefore it acts as one.
  • TaffyCaffy and Mikey B like this

#18 Rimi

Rimi

    Strip Me

  • +Clients
  • 6,121 posts

Posted 26 June 2012 - 08:28 PM

Yeah... That's actually what I was going for. Do any of those have blocks and databases and feed blocks off those databases and templates for different database views?

Also to be quite frank I think ip.content is very easy to understand. The logic is very straightforward and... well.. logical. I can see why IPS has a tough time making documentation for it.
  • Jandar and Mikey B like this

#19 ZakRhyno

ZakRhyno

    All da rhino!

  • +Clients
  • 1,900 posts

Posted 27 June 2012 - 06:15 AM

That's impressive...considering there are no female staff members.

Charles has begun work on the new documentation section, but there is a lot to cover and IP.Content has not been hit yet. Even then, I'm not positive we'll see video articles on things like "making a wrapperless page template". That's the sort of thing video can't explain.



I'll add a note about it.



See, creating a front page template without a wrapper with a top navigation menu bar is not a "basic thing" I'm afraid. That's really the problem. This is a pretty specific customization and even if we showed a basic example of how to do it, it's not necessarily going to cover what an individual is after. This is the difficult part in documenting an application meant to serve as a framework. We can show you how to use the tools (e.g. we have documentation on creating templates, and what various page options mean), but documentation on what you can accomplish with those tools could be worked on forever and still not answer specific questions.


But having a sample to work with does help, just explain it don't work having a working example would help on how to do it.

Yeah... That's actually what I was going for. Do any of those have blocks and databases and feed blocks off those databases and templates for different database views?

Also to be quite frank I think ip.content is very easy to understand. The logic is very straightforward and... well.. logical. I can see why IPS has a tough time making documentation for it.


I would have to disagree, when I first came to IPC I didn't understand it also Shigure you have knowledge that others lack in coding area.

#20 Rimi

Rimi

    Strip Me

  • +Clients
  • 6,121 posts

Posted 27 June 2012 - 07:19 AM

Yes but I didn't have that knowledge when I registered back in November. I gained that knowledge by reading the developer documentation and stalking Marcher and Michael.
  • Tigratrus, TaffyCaffy and Mikey B like this




0 user(s) are reading this topic

0 members, 0 guests, 0 anonymous users