A possible valedictory

[Guest]

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.......

[Rimi]

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.

[bfarber]

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.invisionpower.com/resources/documentation/index.html/_/developer-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.

[Guest]

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.

[Michael]

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.

[Rimi]

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.

[bfarber]

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.invisionpower.com/resources/documentation/index.html/_/developer-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?

[Rimi]

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.invisionpower.com/resources/documentation/index.html/_/developer-resources/user-interface/modal-windows-r764) would be great..or just pictures. Kind of like this one (http://community.invisionpower.com/resources/documentation/index.html/_/developer-resources/user-interface/confirm-action-dialogue-r763).

[bfarber]

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

[bfarber]

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

http://community.invisionpower.com/resources/documentation/index.html/_/developer-resources/user-interface/modal-windows-r764

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

[Royzee]

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

[Rimi]

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.

[Guest]

I realise you are not IBM and do not have the same resources.
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 [*]

[*]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

[Lindy]

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. :)

[Nevo]

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.

[Guest]

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

[Guest]

Just my Two Cents.

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

[Lindy]

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.

[Ryan11433]

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:

[connorhawke]

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.

[Rimi]

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.

Why is this necessary though? The newer, more recent articles (emphasis on newer as in I am not talking about the hook documentation) are pretty well done. I'm speaking from my own perspective of course which is one that comes with zero background in php. But with the documentation I've learned how to use the valuable functions in IPSmember, how to use modal popups, how to make userhovercards, how to use lightbox (and grouping lightboxes!!), how to use autocomplete (with custom databases, I've wanted this since content 2.0), how to display an error and what code number to use, how to manipulate the page title and even add on to the breadcrumbs, how to add to the head (you know the entire article on outputting html is perfect by itself), and how bitwise works (I'm never going to try it but at least I know how it works). What Brandon (and whoever else is working on it, just Brandon's name is sticking out in all the articles I read) is doing with the developer documentation is, I feel, on the right track. The only thing I might have an issue with is the organization of things, but that might be a personal issue. I can't even navigate my way through the marketplace...that and examples, but Brandon said we can use comments to ask for those now.

I'm not trying to suck up, I'm being sincere. In reading the articles that've only popped up over the past month I've learned a lot about IPB and PHP too. Admittedly the only one I've really implemented is ipsmember and the error code one for my hook, but I would've never been able to make that only hook that I've released without those articles. I think with just a little more patience the entire developer documentation will be quite useful.

Although I can agree with you a little...I'd love it if Michael could (and would) contribute to the documentation. I recall after reading one explanation from him I learned everything about using data hooks and his hook making walkthrough was incredibly useful.

So I think in the end I made a big post about nothing. That's ok. It's 1 am and I can't sleep. :(

[connorhawke]

Why is this necessary though?

I never said it was necessary. But it might help. :huggles:

[Rimi]

I never said it was necessary. But it might help.

I don't see any dev articles yet in the 'New Documentation' section btw. Or are they stored somewhere else for the time being?

Just pretend that New Documentation section doesn't exist. Its in the developer documentation of the "old" documentation. :P

I guess then I don't think it'd help.

[connorhawke]

The newer articles do indeed seem relatively well-done compared to the older ones, to the extent that they might not benefit as much from additional help.

In any case, here's to hoping that the older documentation will get a kickshift into high gear.

[Rimi]

Any reason why not? :P Too many cooks spoil the broth or something?

I already said...

I feel that what Brandon is doing right now is working just fine.

And I suppose I agree with that last bit too. As someone who is going to read through a lot of articles its disrupting to see the tone change. For example Brandon and Matt posted interface articles at around the same time. Brandon's article starts off with an intro on what the feature does, why its important, how IPboard uses it etc. Matt's article jumps to the point ans states that here's a feature in IPB if you want to use it then here's how. When reading articles I just assume that either Brandon or Mark wrote it, but this one sounded different and I had to do a double check on the author to see that it had been written by someone else.

So yes, I guess I just prefer everything to be from one person because it feels more consistent. It's just a personal preference, you don't have to agree with me and I don't expect anyone to. Matt's article was just as informative and helpful.

I replied to your post before you edited it. I should stop doing that to people..