Carl Tyler's Blog :: The Domino Designer documentation team screwed us all

Category Domino Documentation
They did us all a disservice by not preparing us for the future. They gave us too much useful information in the documentation. Pretty much every function in the old Domino Designer Documentation gave an example for every function or method, so if you weren't sure exactly how to use it, you'd look at the example and try it out and learn from it, you know, monkey see, monkey do, monkey learn. Those days appear to be gone in the new IBM products. I've been messing a great deal lately with the Connections APIs, the atom feeds look simple enough, but you have to figure out the exact structure yourself, IBM could save developers hours if they just posted an example atom document with every single API call in the documentation, it can't be that hard can it? Surely the test scripts IBM use for testing Connections where they must post thousands of items through the ATOM APIs could be used as examples?

So thanks for nothing Domino Designer documentation team, you set our expectations levels so much higher than what everyone else provides you've made us complacent through making us too efficient at learning your functions and methods, this isn't how it is in the real world!

Comments

1 - We live in a social world. IBM expects that you do it for them (for free). You make the work they get the money. It is a great concept.
Indeed Designer help once was a great resource.

Posted by Henning Heinz At 03:53:57 AM On 04/26/2014 | - Website - |

2 - The same goes for QA Henning.

Posted by Carl At 08:17:31 AM On 04/26/2014 | - Website - |

3 - Carl: well called: couldn't agree more.

Mick

Posted by Mick Moignard At 12:56:17 PM On 04/26/2014 | - Website - |

4 - The nicest backhanded passive/agressive complement I've read in a while. Emoticon

Posted by Giulio Campobassi At 10:04:24 PM On 04/27/2014 | - Website - |

5 - Carl, have you tried the API Explorer in the Playground? It contains the documentation of quite a lot Connections APIs already and we're working on full API coverage. Additionally you can invoke the APIs live from there.

{ Link }

Posted by Niklas Heidloff At 06:26:47 AM On 04/28/2014 | - Website - |

6 - Half the reason I'm a developer is because the designer client was free, and it came with fantastic documentation. I look at some of my 15+yr old code, and it's laughable, but it worked!

I could copy and paste from the help documentation, tweak, and get the results I wanted. If I didn't know what a particular line did, I'd just leave it in:)

Posted by Mike McP At 09:05:13 AM On 04/28/2014 | - Website - |

7 - Carl, you are completely correct, and Niklas, I'm sorry, you are wrong. The API Explorer isn't what we are looking for, we are looking for a simple example we can use. This is very evident in the (not-really) "Documentation" for XPages. The "Help" function seems to have been sent to Dilbert's PHB who describes it as "In order to increase customer satisfaction, we have fired the support staff."

I really don't care that we are told it's better. It's not - unless you are referring to people who no longer have to actually put out a product.

Posted by Brian Moore At 09:10:59 AM On 04/28/2014 | - Website - |

8 - Well I think I'm would agree and actually IBM must of recognized this as they just stopped doing Domino Designer Documentation for the most part.

Problem solved.

Emoticon

Posted by David Leedy At 09:11:30 AM On 04/28/2014 | - Website - |

9 - I didn't know that existed Niklas, and in all my searches for help on a couple of connections APIs that site never came up.

It didn't help though, the functions I wanted help with don't exist on that site. Like IBM wikis, it's something that has been started and published when it isn't yet finished. People need documentation and resources that are complete.

I look forward to seeing it completed with an example for every Connections API call though.

Thanks

Posted by Carl Tyler At 09:16:00 AM On 04/28/2014 | - Website - |

10 - Here's an example of what I mean Niklas. Lets say you want to add a file to the Media Gallery. There are tonnes of examples, but none of them are about creating the file:

{ Link }

Posted by Carl Tyler At 09:21:15 AM On 04/28/2014 | - Website - |

11 - Carl, I'll take a look whether APIs to write events and files to media gallery exist.

For Connections app dev go to { Link } to find these resources.

Brian, I'm not sure I understand. The playground contains already around 800 code snippets. There might still be snippets missing as Carl pointed out. Is that your point or do you expect something different?

Posted by Niklas Heidloff At 09:46:20 AM On 04/28/2014 | - Website - |

12 - Carl, is that what you're looking for regarding events?

{ Link }

You can try the REST API call via the platground { Link } "Creating community events"

An easy JavaScript and Java snippet is indeed missing.

Posted by Niklas Heidloff At 10:03:04 AM On 04/28/2014 | - Website - |

13 - Yes Niklas, and you help explain the reason for my blog post. The Connections API contains information, but no useful example .

That Creating Community Event in the playground is missing lots of information, for example the date and time of the event, pretty important stuff. So proves to be pretty much useless.

Posted by Carl Tyler At 10:10:47 AM On 04/28/2014 | - Website - |