Jump to content


Photo
- - - - -

A possible valedictory


  • Please log in to reply
49 replies to this topic

#1 CessPoolCleaner

CessPoolCleaner

    Code GooRoo

  • Visitors
  • PipPipPipPipPip
  • 771 posts

Posted 28 April 2012 - 08:59 PM

Now this is not a 'I am leaving and I want to vent' it is more of 'I really like this software butt'....

A long time ago I talked my then site partner into moving from phpBB to InvisionPower the main reasons were the support and the more stable nature of the beast. Back then phpBB was stuck trying to release the next version and it was hurting our site. Then, as now, the cost was our only downside as we were basically a free site running on donations. We went to a membership model (way before Subscriptions/Nexus) and that kept our head above water. Since then as IPS released stuff we, then me when he retired from the site, have pretty much always stayed with the IPS model, when Nexus came out I dumped aMember, even though I was making serious dosh from doing support/cutom work. Eventually I even dumped Wordpress and my own software system built with cmsBuilder and moved it all over to IPS products.

On a planetary scale I am not a big customer only four licenses with add-ons in each about $350 a year in support costs so compared to a number of other clients definitely small cheese. As a developer I have never been a fan of the way applications/hooks work, mainly applications. The big whinge I have is the documentation/sample code which I believe is totally atrocious, the huge whinge is the lack of reasonable information on Nexus (as it is encoded) as mentioned I made serious money working with aMember and I would have thought I could have done all sort of nice things for people with the base of Nexus but the inablilty to get into the processing is very frustrating. I did do a DVD fulfillment addon for my site but even something as trivial as that was a right royal PITA.

Sorry guys, you keep telling us you will improve the documentation but you have said that for the last three major releases and still the documentation doesn't have reasonable examples of the API calls, even the calling information is difficult the result is needing to look at the code continually to see what to do to achieve stuff. Unfortunately there doesn't seem to be a solution as each version iteration has only kept making it harder not easier, it aint as though I am a coder in swadling maybe it is that I have gotten old and cranky but I am really frustrated and the main causes are IP.Content & IP.Nexus primarily documentation and weird behaviour. The reason I have always loved IPS is the support, top notch, absolute best practice with wonderful people but it is not enough!

As I said at the top no decision point has been reached, but I am at the tipping point. To take your breath away I am considering Expression Engine mainly because as a coder it gives me 'control' uses a template system that is easy (for me) and that I may be able to get back into development which is what I like to do.......
  • Michael, Marcher Technologies, Con and 1 other like this

JLogica .. has left the building .. Hope you all have a lovely and productive life.

 


#2 Rimi

Rimi

    Strip Me

  • +Clients
  • 6,121 posts

Posted 28 April 2012 - 10:02 PM

The more recent documentation articles have actually taught me a lot...they're not the best at showing examples, but they're better than nothing.

#3 bfarber

bfarber

    RBT-KS

  • IPS Management
  • 28,561 posts

Posted 30 April 2012 - 09:14 AM

We've actually been posting a ton of developer documentation as of late. I posted/updated roughly 4 or 5 articles just last Friday, and probably another 5-10 throughout the course of last week.

http://community.inv...oper-resources/

We currently have over 150 developer documentation articles and are working on new ones all the time. We blogged about this at the end of March so everyone was aware. Further, we have a full set of phpdocs online that anyone can view.

I must say I'm a bit surprised by this topic. While we realize documentation could use some work, developer documentation specifically has been filling out at a rapid pace over the last month or two. I'm not really sure how much faster we can work on it, or what you are looking for that is missing. The "creating an application" (and hook) documentation is forthcoming, but as you can imagine those are very big projects and not quick one hour write-ups, so they took more time to get finished.
  • mat206, Con and Mikey B 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.


#4 CessPoolCleaner

CessPoolCleaner

    Code GooRoo

  • Visitors
  • PipPipPipPipPip
  • 771 posts

Posted 30 April 2012 - 05:55 PM

We've actually been posting a ton of developer documentation as of late. I posted/updated roughly 4 or 5 articles just last Friday, and probably another 5-10 throughout the course of last week.


The problem is that you know about what you are writing in such detail that almost anything seems to be enough. I suffer form the same syndrome when I used to write technical documentation for projects. Having the actual developers writing documentation (other than the PHPDocumenter stuff) never works you know too much. You can't write the stuff for people who don't know so that they can easily make use of the stuff.

I loathe doing documentation but I offered to do the developer stuff if I was given access for answers to the questions necessary. I was told a documention person was hired. I assumed you had hired a technical writer but you are still falling for the trap that a programmer/developer is about the last person you want writing technical documentation about their babies.

We currently have over 150 developer documentation articles and are working on new ones all the time. We blogged about this at the end of March so everyone was aware. Further, we have a full set of phpdocs online that anyone can view.


That was still broken last time I looked for help, most of the developer stuff has been in the toilet since 3.2 unsatisfactory is the only word possible .. sorry if this offends.

I must say I'm a bit surprised by this topic. While we realize documentation could use some work, developer documentation specifically has been filling out at a rapid pace over the last month or two.


My assessment of the dox is that they are inadequate. They have a textual representation (for the most part) of the call being described.

Documentation should be about showing how to use the target not a prose version of the options. example IPSMember::load something nice and simple has one sample;
$members = IPSMember::load( array( 'john@doe.com' ) );
Which shows absolutely the simplest call possible assuming defaults. Sure this one is easy but that's the point the samples need to be real.

As I put in the message about writing documentation, I am not talking out of my arse when I did this for a living I used to be technical lead for projects where I had 60+ programmers working for me back in those dayz technical writers were something IBM had and we had to do the best we could.

JLogica .. has left the building .. Hope you all have a lovely and productive life.

 


#5 Michael

Michael

    Meet Jay

  • +Clients
  • 19,587 posts

Posted 01 May 2012 - 07:58 AM

I agree with this, the documentation here is the one aspect that still needs the most work to bring it up to snuff. There may be a lot of good docs out there, but try finding them if you're not the one who wrote them. There are 2 different Documentation links in the navigation dropdown; the new section only has 5 articles in it that I can see, and the old one seems to have had several attempts at organizing it, none of which have been successful. It's got this 'New Docs (work in progress)' category in it, so a lot of stuff that would logically be in some other category may be there instead. And then the developer category there has a '-TEMPORARY STORAGE-' category which has other docs in it which should logically go in another category too. In addition, somewhere out there is doxygen-generated documentation too, but I don't think it's actually linked anywhere.

The only way I am ever able to find anything in the documentation now is to search for some key word in the code I know would be in a certain article. Otherwise if I ever need to refer someone to documentation on how to do something I generally just try and explain it myself. It's all well and good for those of us who have worked with the software for years and are comfortable getting our hands dirty digging through the code, but I'd hate to be a new modder trying to make sense of this documentation.

You really need to start by organizing everything. Pick one place for it to go and put it there. Lay it out logically so that brand new people can understand where to find the docs that talk about getting started with the software, and explaining how to use the tools out there to manage their site. And then also organize the developer documentation so someone can look at what's there and actually create something. I'll take the hooks documentation as an example, a lot of those docs talk only about the PHP file you have to create, and some don't even show any code in them. A person should be able to open one of those docs and be able to create a hook from it, and I don't see a new person being able to do that today.
  • .Brian, TaffyCaffy, Marcher Technologies and 1 other like this

Contact Me: Email · Facebook · Twitter · Google+


#6 Rimi

Rimi

    Strip Me

  • +Clients
  • 6,121 posts

Posted 01 May 2012 - 09:39 AM

I agree with Michael on the organization of things. If I need to go back and find a doc I literally open all the categories in new tabs and browse through the list or search via keywords like he does.

As for the docs themselves, the hook ones in particular aren't very helpful that's true. But Brandon already said that they're going to work on that. The more recent articles like how to use autocomplete, modal windows, how to add profile tabs were pretty good.

#7 bfarber

bfarber

    RBT-KS

  • IPS Management
  • 28,561 posts

Posted 01 May 2012 - 09:42 AM

The problem is that you know about what you are writing in such detail that almost anything seems to be enough. I suffer form the same syndrome when I used to write technical documentation for projects. Having the actual developers writing documentation (other than the PHPDocumenter stuff) never works you know too much. You can't write the stuff for people who don't know so that they can easily make use of the stuff.

I loathe doing documentation but I offered to do the developer stuff if I was given access for answers to the questions necessary. I was told a documention person was hired. I assumed you had hired a technical writer but you are still falling for the trap that a programmer/developer is about the last person you want writing technical documentation about their babies.



That was still broken last time I looked for help, most of the developer stuff has been in the toilet since 3.2 unsatisfactory is the only word possible .. sorry if this offends.



My assessment of the dox is that they are inadequate. They have a textual representation (for the most part) of the call being described.

Documentation should be about showing how to use the target not a prose version of the options. example IPSMember::load something nice and simple has one sample;

$members = IPSMember::load( array( 'john@doe.com' ) );
Which shows absolutely the simplest call possible assuming defaults. Sure this one is easy but that's the point the samples need to be real.

As I put in the message about writing documentation, I am not talking out of my arse when I did this for a living I used to be technical lead for projects where I had 60+ programmers working for me back in those dayz technical writers were something IBM had and we had to do the best we could.


Keep in mind, we are not IBM. ;) Frankly, our documentation staff are absolutely not who you want writing technical source-code level developer documentation. We have people that are/will be working on the user-level documentation (where I agree you don't want developers writing the articles), but someone who doesn't know PHP, or barely knows PHP, is not the best person to write up source code examples of how to do x or y.

Anything that is not fleshed out enough you should comment on and request to be updated. We have encouraged this in the past. The comment form states "Do you have a tip, alternative approach, or extra information you want to share with the IPS community regarding this article? Feel free to contribute by adding a comment!" - we absolutely DO want feedback about existing docs that need to be improved or expanded upon. How is one to know what is lacking if no one speaks up?

The phpdocs (doxygen export) work just fine. Can you clarify what you mean by them being "in the toilet"?

I agree with this, the documentation here is the one aspect that still needs the most work to bring it up to snuff. There may be a lot of good docs out there, but try finding them if you're not the one who wrote them. There are 2 different Documentation links in the navigation dropdown; the new section only has 5 articles in it that I can see, and the old one seems to have had several attempts at organizing it, none of which have been successful. It's got this 'New Docs (work in progress)' category in it, so a lot of stuff that would logically be in some other category may be there instead. And then the developer category there has a '-TEMPORARY STORAGE-' category which has other docs in it which should logically go in another category too. In addition, somewhere out there is doxygen-generated documentation too, but I don't think it's actually linked anywhere.

The only way I am ever able to find anything in the documentation now is to search for some key word in the code I know would be in a certain article. Otherwise if I ever need to refer someone to documentation on how to do something I generally just try and explain it myself. It's all well and good for those of us who have worked with the software for years and are comfortable getting our hands dirty digging through the code, but I'd hate to be a new modder trying to make sense of this documentation.

You really need to start by organizing everything. Pick one place for it to go and put it there. Lay it out logically so that brand new people can understand where to find the docs that talk about getting started with the software, and explaining how to use the tools out there to manage their site. And then also organize the developer documentation so someone can look at what's there and actually create something. I'll take the hooks documentation as an example, a lot of those docs talk only about the PHP file you have to create, and some don't even show any code in them. A person should be able to open one of those docs and be able to create a hook from it, and I don't see a new person being able to do that today.


Documentation in general is being worked on - in this topic I'm only talking about developer documentation specifically.

Documentation is searchable in the main site search (though you need to select the correct database in the left hand filters).

I can't speak much about the "New Documentation" - I agree that's confusing, but that is something the main user-level documentation team is working on, and not something I have much control over. The "-TEMPORARY STORAGE-" category is exactly what it sounds like - it is only a temporary category that we moved all pre-3.3 docs to until they are updated. It had probably 50 docs in it originally. It's now down to less than 20, and as they are updated, they are moved back to the correct location. I apologize for confusion with this category, but we didn't want to delete what can be useful starting points for updated documentation articles, so we simply moved them to a temporary category until they are updated. I can hide this category if that actually helps - I just figured until they are updated, someone may want to refer to the older version of the article as much of the information is still relevant.

I agree the doxygen docs need to be linked and we will do so.

ALL developer documentation is housed at

http://community.inv...oper-resources/

It MAY get moved to the new documentation location when that is ready (per the user-level documentation team), but if you just go to this link (or go to the "Documentation (pre-3.3)" link and click on "Developer Resources", it's fairly well organized right now I'd say. What is confusing about the setup at the above link itself? If it helps, we could add a link directly to this category in the dropdown menu?
  • Misi likes 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.


#8 Rimi

Rimi

    Strip Me

  • +Clients
  • 6,121 posts

Posted 01 May 2012 - 09:50 AM

The comment form states "Do you have a tip, alternative approach, or extra information you want to share with the IPS community regarding this article? Feel free to contribute by adding a comment!" - we absolutely DO want feedback about existing docs that need to be improved or expanded upon. How is one to know what is lacking if no one speaks up?

I've left comments at least three times, but comments have to be approved and none of mine have...besides the way that's worded makes it seem like asking questions and asking for further clarifcation is not encouraged in comments. I mean I'm more inclined to ask questions in the topic that's generated in the Feedback board.

For me the only feedback is having examples of the code in action. That's really all I need to understand it more. Like pictures and examples for this doc (http://community.inv...al-windows-r764) would be great..or just pictures. Kind of like this one (http://community.inv...n-dialogue-r763).
  • Kiryu likes this

#9 bfarber

bfarber

    RBT-KS

  • IPS Management
  • 28,561 posts

Posted 01 May 2012 - 02:33 PM

Yes, please post comments to the relevant documentation article. I only work through developer doc articles, and I will approve comments when I see them.

I'll clarify the message on the comment form

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.


#10 bfarber

bfarber

    RBT-KS

  • IPS Management
  • 28,561 posts

Posted 01 May 2012 - 02:57 PM

I've posted an example in the doc you referenced, along with some screenshots. :)

http://community.inv...al-windows-r764

(I really am willing to take in feedback on specific docs that need updating, I promise ;) )

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 Sandi_

Sandi_

    Code Addict

  • Members
  • PipPipPipPipPipPip
  • 1,096 posts

Posted 01 May 2012 - 03:14 PM

I'm glad IPS will be including more examples. Sometimes they are sorely needed.

Twenty years ago we had Johnny Cash, Bob Hope and Steve Jobs.

 

Now we have no Cash, no Hope and no Jobs. PLEASE! Don't let Kevin Bacon die.


#12 Rimi

Rimi

    Strip Me

  • +Clients
  • 6,121 posts

Posted 01 May 2012 - 03:17 PM

I've posted an example in the doc you referenced, along with some screenshots. :smile:

http://community.inv...al-windows-r764

(I really am willing to take in feedback on specific docs that need updating, I promise ;) )

Yes, what you did there was perfect. Now I can more easily understand what you meant by balloon. And then telling us how you did it (HTML block in a page) lets us try it ourselves the exact way you did.

Thanks for listening. This is what I was looking for.

#13 CessPoolCleaner

CessPoolCleaner

    Code GooRoo

  • Visitors
  • PipPipPipPipPip
  • 771 posts

Posted 01 May 2012 - 05:32 PM

I realise you are not IBM and do not have the same resources.
  • Using the dox online is a pita .. I should be able to run them locally. It is ok for you guys with adsl(ie fast) but searching/browsing through the system is sooooo tedious
  • You example of a good doc page did you load it? The code sample?????? It dunna look all dat good huh!
  • More than me has asked that a reasonable 'hello world' applcation be written that has all the bits there so that we can use that as a start off to what we need .. ie change the dir name to our app and we have our_app_hello_world
  • Making a system IN_DEV is still broken
  • Exporting an application from in_dev is (my opinion) absolute CRAP I should be able to say gimme my app and get it all packaged not have to remember to import/export the skin, import/export the language, reload hooks etc etc etc ... bad bad bad
  • NEXUS! <<<< If it aint in the old source I have the I am STUCK ... at the very least make the source available to people who do stuff with Nexus as I said there are a number of things that could be added but no access leaves us in the cold ... did I mention dox?
  • Searching/browsing the dox and the so called KB sux big time have a look at Q2A I have to run this on RBR as Content is totally useless when it comes to managing a KB. Add this functionality to Content and use it you will love it and so would we ... don't tell me it is already possible, if it were you would have done it already.
  • Feedback .. you guys don't give us feedback when we make suggestions. It is all well and good to use one of the standard excuses that have been used but if someone makes a suggestion and it is accepted say so, if it is rejected say so ... then we have the chance of possibly explaining in more detail what it is we want/need.
  • sigh I am getting worked up again just trying to go through my list...
  • How about Wordpress it auto downloads its own updates, can install stuff directly off their equiv of the marketplace

  • svit likes this

JLogica .. has left the building .. Hope you all have a lovely and productive life.

 


#14 Lindy

Lindy

  • IPS Management
  • 6,652 posts

Posted 01 May 2012 - 10:37 PM

No need to get worked up. We will address this is in our next management meeting. As you'll note, we do listen and will make improvements accordingly, as we can. :)

Lindy Throgmartin

Chief Executive Officer
Invision Power Services, Inc.

E-Mail: LThrogmartin@invisionpower.com


#15 Nevo

Nevo

    Webmaster

  • +Clients
  • 1,107 posts

Posted 01 May 2012 - 10:56 PM

I cannot agree with you regarding the documentation because it shouldn't be up to IPS to do any documentation whatsoever. If you want to learn more about their system and how to work with the applications and hooks, that's your problem and there are alot of people I know in the IPS community that clearly know how to do what you'd want with ease, Your problem is you don't have contact with them therefore you are struggling to create your custom website. IPB uses very advanced programming and afterall, theres always IP Content... So i cannot, for the life of me, understand why you are having such issues... You literally take that any code, including an entire CMS and put it into Content and call it a day!

IPS has introduced a new level of CMS that is very different from the rest because from what i understand, they got tired like all the rest always adding those changes in the code so they came up with the whole APP and Hook functionality, Simply Brilliant and fantastic to use! Again, just because you're lacking the documentation doesn't mean IPS hasn't created it or isn't planning on creating it... FYI, they've done a great job so far and they are only starting... Give them some time or hire someone to build that functionality for you or use Content! You have so many options, bashing IPB isn't going to help.... Just my Two Cents.

Did you like my Post? Did I Help you anyway with the contents of my Post? Well Than...

Please say Thank you by Pressing the Button on the right side of the my Post:  gallery_146014_1635_618.png


#16 CessPoolCleaner

CessPoolCleaner

    Code GooRoo

  • Visitors
  • PipPipPipPipPip
  • 771 posts

Posted 01 May 2012 - 11:12 PM

No need to get worked up. We will address this is in our next management meeting. As you'll note, we do listen and will make improvements accordingly, as we can. :smile:


Try ticket 790353

JLogica .. has left the building .. Hope you all have a lovely and productive life.

 


#17 CessPoolCleaner

CessPoolCleaner

    Code GooRoo

  • Visitors
  • PipPipPipPipPip
  • 771 posts

Posted 01 May 2012 - 11:13 PM

Just my Two Cents.


You are obviously allowed to have your own opinion and I am just as permitted to disagree.

JLogica .. has left the building .. Hope you all have a lovely and productive life.

 


#18 Lindy

Lindy

  • IPS Management
  • 6,652 posts

Posted 01 May 2012 - 11:59 PM

Try ticket 790353



Thanks - I'm unsure how that ticket ended up closed, but let me check into it and we'll get back to you.

Lindy Throgmartin

Chief Executive Officer
Invision Power Services, Inc.

E-Mail: LThrogmartin@invisionpower.com


#19 Ryan11433

Ryan11433

    Spam Happy

  • +Clients
  • 527 posts

Posted 02 May 2012 - 12:07 AM

Thanks - I'm unsure how that ticket ended up closed, but let me check into it and we'll get back to you.


That used to happen sometime when someone at your department ends up being tired or want the person to shut up. :sad:
Expert Webmaster - Scripting webpages - Editing webpages - Modifying images - Loving Music - Chatting - Partying - What else could it be?

#20 Con

Con

    XR3X

  • Members
  • PipPipPipPipPipPip
  • 1,590 posts

Posted 02 May 2012 - 12:34 AM

Just throwing a suggestion out there: wikify the dev articles? As in, allow seasoned developers (several of whom have commented above) to actively take part in editing the articles. The edits don't have to be applied immediately, but can be reviewed, e.g. by bfarber and whoever else is in charge overall with those. Sure, there's the commenting system, but I think that developers would be more encouraged to develop the articles if given a more active part in writing them.
  • Michael, mat206, NewRockRabbit and 2 others like this
sig.png




0 user(s) are reading this topic

0 members, 0 guests, 0 anonymous users