49 replies to this topic

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

[Con]

Why is this necessary though?

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

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

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

[Con]

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

[Con]

Good points.

[bfarber]

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

The vast majority of your suggestions have absolutely nothing to do with documentation. I encourage you to post individual feedback topics for things not related to documentation in the appropriate areas.

1) You are free to print and/or download documentation articles using the buttons below them. By keeping them online in a database, we can update them (as we are doing now...) when changes occur.

2) I'm not sure what you are referring to. I don't think I linked to a documentation article and said "this is a good article". Everyone has a different opinion on what "good" is.

3) We have one, it is out of date, and will be updated. This is why it's currently in the "temporary storage" category, as I mentioned previously.

4) This has nothing to do with documentation...however I am not aware of anything "broken" about it, except a recently reported bug having to do with the XML skin (which is fixed for 3.3.2). I use IN_DEV locally, as do most third party developers I expect.

5) This has nothing to do with documentation.

6) We cannot make the source code available, I'm afraid. If there are things not documented well enough between the phpdocs and the individual developer documentation articles, please let us know exactly what you want to see documented with Nexus.

7) I'll take a look at the site, but this sounds like a preference more than anything. We have categories, and articles inside those categories. I'm honestly quite confused about what is "difficult" navigating the documentation. Perhaps some clarity on what exactly is confusing or difficult about clicking on a category, and then an article in that category, would help. (I'm not trying to be facetious either, just for the record - I truly don't understand what is confusing about the navigational structure).

8) This has nothing to do with documentation.

9) This has nothing to do with documentation.

10) This has nothing to do with documentation.

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.

We are toying around with an idea similar to this, but I don't have any information on it yet. IIRC, when we move over to the "New Documentation" setup, we want to get the community more involved with the official documentation areas. Right now there is separate database where members of the community can contribute, and we agree this is a little fractured.

[CessPoolCleaner]

Can I download it all in one go ?? Don't think so.
As an example of not polishing look at the code sample, nicely aligned code mangled by the display system
May not be dox but it is the same issue

[Marcher Technologies]

Beyond and above(though this includes nexus, the grief, not me ripping the source open... I WISH lol).
I am dog tired of hunting your source for example usages.... allow me to tell a bit of a tale.
I have yet to see a documented full usage of the forums postClass API, Michael was kind enough to post how to make a new topic, but this is basic basic needs(adding a reply, updating the post cache when modifying via hook, etcetera)... I literally found it to be easier to properly use Michael's tutorials post API with less hassle, grief and headache, without documentation, and that makes me hurt a little.
Not to mention the whole graveyard of undocumented app methods that ARE first party Apps.
The comments are not that helpful, and this is coming from somebody has ripped open the whole of nearly every app... there's a LOT of useful items that lack usage examples of any kind.
And we all know using a method incorrectly is about 10x worse than not using it at all.... usage examples of the apps API is a gaping void, when it should be readily available.

[Marcher Technologies]

Not to state I'm not absolutely loving the thorough Kernel docs BTW, I really do appreciate that, just making my opinion that documentation is not finished at all with a simple update of what is there.... we have big holes ATM as developers.
Also... as a note... organization and usability wise the PHPDocs are... quite bad.... its not even segregated by app, is a total pain to navigate from one class to another in an application.

[Marcher Technologies]

also... would it kill anyone to run the PHPDoc on ALL of nexus? there is well over half the application missing here... and ATM that is the best method list we modders have to work with.

[Marcher Technologies]

also... would it kill anyone to run the PHPDoc on ALL of nexus? there is well over half the application missing here... and ATM that is the best method list we modders have to work with.

my bad... is search issue, irrelevant... search explicitly will not return the full results when i type in nexus even though it lists, first statement of organization of those stands, is mess.

[bfarber]

Beyond and above(though this includes nexus, the grief, not me ripping the source open... I WISH lol).
I am dog tired of hunting your source for example usages.... allow me to tell a bit of a tale.
I have yet to see a documented full usage of the forums postClass API, Michael was kind enough to post how to make a new topic, but this is basic basic needs(adding a reply, updating the post cache when modifying via hook, etcetera)... I literally found it to be easier to properly use Michael's tutorials post API with less hassle, grief and headache, without documentation, and that makes me hurt a little.
Not to mention the whole graveyard of undocumented app methods that ARE first party Apps.
The comments are not that helpful, and this is coming from somebody has ripped open the whole of nearly every app... there's a LOT of useful items that lack usage examples of any kind.
And we all know using a method incorrectly is about 10x worse than not using it at all.... usage examples of the apps API is a gaping void, when it should be readily available.

Not to state I'm not absolutely loving the thorough Kernel docs BTW, I really do appreciate that, just making my opinion that documentation is not finished at all with a simple update of what is there.... we have big holes ATM as developers.
Also... as a note... organization and usability wise the PHPDocs are... quite bad.... its not even segregated by app, is a total pain to navigate from one class to another in an application.

No one said we were done. In fact, I'm pretty sure we've been thoroughly clear that it is a work in progress that has started, and we are actively working on it. I pointed out in this thread, for instance, I added a good 5-10 new articles last week. If we were done, surely we wouldn't still be adding.

also... would it kill anyone to run the PHPDoc on ALL of nexus? there is well over half the application missing here... and ATM that is the best method list we modders have to work with.

As I take it you discovered by your last post, we've run the phpdocs on the whole of the suite - we didn't omit any files.

[Rimi]

I was looking at some of those kernel articles..just skimming. I'm wondering if for each article you can also provide a file of it being used somewhere in the IPS suite? That way we can see a live example of it and understand what's going on in the code through the documentation.

Additionally can I request an article on how to send PMs? Would like that one very much..

[bfarber]

(Replying to this topic isn't really the best way to note these things - your response will get lost eventually).

I'd recommend replying to the articles that need better examples stating so. I'll make a note about sending pms.

[Rimi]

Well ok. It was pretty on topic though.

[podz_en]

Fix those broken links in your documentations! Everything is broken!

[podz_en]

Is documenting everything a chore to you? Or you're better changing the methods every time you want to? Please make everything in-sync! Why is it you're releasing versions that have not had documentation?!

[bfarber]

Is there a specific piece of documentation you are looking for?

[Wolfie]

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.

This gives me an idea. Will need to 'tweak it' some in my mind, but I have an idea that could be very useful indeed.