Loading presentation...

Present Remotely

Send the link below via email or IM

Copy

Present to your audience

Start remote presentation

  • Invited audience members will follow you as you navigate and present
  • People invited to a presentation do not need a Prezi account
  • This link expires 10 minutes after you close the presentation
  • A maximum of 30 users can follow your presentation
  • Learn more about this feature in our knowledge base article

Do you really want to delete this prezi?

Neither you, nor the coeditors you shared it with will be able to recover it again.

DeleteCancel

Make your likes visible on Facebook?

Connect your Facebook account to Prezi and let your likes appear on your timeline.
You can change this under Settings & Account at any time.

No, thanks

Blackbaud CRM SDK, API, and Technical Documentation Survey Results Part 1 – Open Ended SDK Questions

Foster a reliable, consistent process within Blackbaud to create API documentation for our Infinity Web APIs and any other future APIs.
by

Trip Ottinger

on 11 December 2012

Comments (0)

Please log in to add your comment.

Report abuse

Transcript of Blackbaud CRM SDK, API, and Technical Documentation Survey Results Part 1 – Open Ended SDK Questions

Documentation Survey Output Process Products Engineers help document
source code /key features / assemblies Create an API documentation framework that generates API documentation from code, merges engineer authored usage notes/remarks, and code samples into HTML pages available either internally and/or externally. Improving Tech Docs and References The Blackbaud Products User Education team developed this survey to help prioritize the most relevant technical documentation needs surrounding the Infinity SDK and Web APIs. Questions centered around
Segmentation
Technical reference needs and priorities
Open ended questions about
Overall development experience
SDK install
Improvements with SDK templates, utilities Lots of very good comments
Code commenting within specs and assemblies needed
Document how certain features work
Steep learning curve without training and docs
More samples and examples needed Comments about the overall development experience for the Infinity SDK and Web APIs.   Code commenting would help tremendously, when visual studio intellisense pulls up a function it would be helpful to have the code comments for the method description and parameter descriptions. This would make development quicker by eliminating pauses to check documentation or go ask someone who might know what that particular function is meant to do.
Developing against knows spec types gets easier, but learning new spec types is a slow process.
It's a very flexible, powerful platform but makes for a very difficult learning experience.
It is good and very polished. The learning curve is steep for someone without training.
More "How do I" types of scenarios would be helpful as well. Generally speaking, developing with Infinity SDK is very easy and straight forward. There are definitely some glaring gaps in documentation of more advanced development features, but I'm not sure how much of that overlaps with general SDK users vs. Infinity developers.
The development experience can be made better by providing documentation/samples of some features which are not documented so far (prompts from UI models, multiple form handling etc).
The thing I see clients struggle with the most is understanding how the core product works prior to customizing it. Not only from a front-end standpoint, but from a back end as well. Our front end documentation leaves a lot to be desired, so most of the time I end up saying "just test it and see what happens" when people are asking how to do something or why it behaves a certain way. The Enhanced Revenue Batch is a great example. I haven't see much documentation regarding import field mapping, such as mapping multiple designations or revenue streams, and the columns are sometimes not well named. It's very challenging for clients to write a customization when they don't even know how standard functionality works.
Other than the concern over understanding the OTB functionality, I think it is very good More, More, More... Learning more about SDK has made my job easier. It has made me understand the infinity platform better.
Easy to deploy and use.
Good.
Excellent
Overall, generally it's been good.
They are quite easy to use.
Blackbaud is a wonderful application and its been a great learning and creative experience for me work on BB Customizations.
Its been a good experience overall. it provides good development experience, specially with all the new functionality and enhancements coming in
It is a fantastic tool - it's extensibility and ease of use is very appealing to internal and customer developers. I have worked with a variety of 3rd party development tools, and our SDK easily outshines them all. 
I would give 4 out 5 for overall development experience.
At first glance, it seems pretty simple to develop new features until you try to do something that is even slightly outside the box. I wish there were more end points that would do partial processing of the record so I do not have to copy bits and pieces from other specs.
It's been moderately good. Wish there was more support for JavaScript very good comments about the overall dev experience Additional General Comments A lot of stuff is still restricted like smart query.. require more ways to extend it
The UIModel needs to mature to the point where Visual Studio does the work for wiring up HTML and code behind files with the user interface on a design surface.
If we could also have C# compatibility, then that would be great and would also help for development
Blackbaud developer forums should be more responsive.
Pretty good but have only worked with certain parts of it so far. One point though is the large number of artifacts you need to create, sometimes. Especially for business processes. Once you get through all the pages (parameter set plus status) and then all the forms and datalists etc to go with those you end up with a surprisingly large amount of stuff. The business process itself can be the least of it.
SDK need to improve its Cache mechanism in client projects. Job Role
Experience Level
How you use SDK/API
Length/Frequency of SDK and API use Segmentation (Gather data to separate the respondents into distinct groups) Build consensus among the engineering leaders around a consistent process within Blackbaud to create documentation for our Infinity Web APIs, features, assemblies, App Engine APIs, etc. Relying on senior engineers to lead the adoption of responsibility for core API docs by the engineering teams Simple
Samples
Side by side installs
Utility integration with VS What do you like about the current SDK install? Simple, easy to install, not too difficult to complete, hassle free install, generally easy to use for an Enterprise Software install, Minimum installation/configuration effort, Installation is more easier now as compare to older version of SDK
The samples, it has provided samples, KitchenSink addition has been really nice also
Fast and allows side-by-side installs with other versions
I like the integration of the utilities with Visual Studio being updated with each install What do you like about the current SDK install? Wizards that populate most of the specs for me
Easy to locate all relevant spec types quickly. The standard format is also a plus between spec types.
It's pretty easy to use once you know VS.
Intellisense is fantastic if you're unsure of exactly which attributes to use. It's nice to be able to just go off the template.
It's automation.
Lots of automatically generated forms. Hard to figure out but make work a lot easier once you begin to understand them.
I primarily work with the Catalog and UIModel project types. They are relatively straightforward and easy to use.
The shortcuts
It is relatively easy to author new features using the SDK. Let's file this under miscellaneous... Other good feedback (not necessarily installation related) about the SDK Difficulty with Multiple Versions
VS2008 versus 2010
Steep learning curve without documentation
More documentation needed within the XSDs
More examples and documentation needed of advanced attributes What do you NOT like about the current SDK install? There does not seem to be a version check against the database selected.
We can't install multiple versions of the application on the same machine.
There should be an option of installing multiple SDKs. Developers usually work on more than one versions of SDKs and need to install/uninstall different versions as per requirement.
Version switch does work as cleanly as I would like. Also no uninstall.
Once it missed LoadSpec integration in Visual Studio. I don't know if it happens often. There should be an option to install multiple SDK versions at once.
External Vstudio tools like load spec don't caption themselves with side-by-side versions in mind - example: if i install 2.93 and 2.94, i have two indistinguishable "load spec" commands on the tools menu. Also it should let you customize defaults like the author tag when you install.
Requires VS 2010 or higher
It would be nice if it also automated the assignment of current templates to the associated version of Visual Studio (in cases where, for example, VS 2008 and 2010 co-exist, if the templates that were .net 3.5 could automatically apply to 2008 and all the sdk templates could be automatically applied to 2010.) Version adversion More examples are needed for different spec types. I am very familiar with the specs I use daily (reports, stored procedures, etc.) but creating something that I haven't worked on before take a large ramp-up time. This could be done by examples on our internal dev sites or by adding additional comments into the templates.
There seems to be a lot of information missing - just things that aren't documented. My biggest frustration with Infinity has been in learning how to do something for the first time when a lot of what I'm trying to write is not documented directly. There is a very steep learning curve.
Doesn't come with a lot of documentation and the attributes / xml elements you have to sometimes discover on your own.
Documentation could be better, especially regarding advanced functionality. Many of the examples are too simplistic to be able to extrapolate from and many less often used attributes are nowhere to be found in any of the technical documents.
Documentation for SDK
Need too many utilities to author new features.
Existing OTB functionality seems somewhat black-box. the interaction with the SDK requires inferring activity that is sometimes hard to predict More examples and xsd documentation, please How should we change the distribution of the SDK?  Check all the statements you agree with. Better documentation within spec schema
Ability to default template values such as Author
Better formatting
C# The SDK ships with Visual Studio catalog item (spec) templates to help build features such as data forms, query views, and batches. What improvements or additions would you like to see to these templates? Description what does the spec do
Additional examples/comments of how the specs should be filled out and/or how they affect the results.
better documentation on what some of the settings are
Include more of the new attributes / elements in the templates.
more examples and extensive descriptions for each attribute and element available in the specs
More explanation behind each element?
It would be nice to have more information on the less-frequently used templates
As the product continues to evolve, new templates are also added that developers are often unaware of, so documentation outlining these would be helpful.
Although intellisense is available for all the attributes and elements, perhaps the intellisense might include an example of the attribute/element use (where applicable). More documentation, please.... The specs templates provided are very comprehensive. I can think of any changes to these.
More wizards
Visual IDE for UI layout for UI Model and HTML
Loadspec utility should be able to load all the specs available in the current project/solution.
The categorization is incorrect, for example UI templates are in the "server" category. Hard to tell if a template is still "best practices". Maybe we should version the SDK.
match up a little better stylistically. There are little differences between all of them that could easily be made uniform, such as spacing, capitalization, etc. Just makes it look better.
Change the default on the Author to not be "Blackbaud Product Development". Make sure it's tested better.
Change certain defaults -- like 'Blackbaud Product Development" for the author!!!
It would be nice to be able to 'default' some of the template items, like the author, etc.
Couple of versions have spelling mistakes on key field names.
Get rid of tabs and messy formatting in the templates. More suggestions and formatting issues Templates in C#
Can we also have templates that are compatible with C#, currently it runs on VB.net which is ok, but it would be better to also have C# compatability. C# Documentation
Need "Unload Spec" tool
Complete and include
Batch generator
BP generator
Spec Helpers
Improvements to Refresh UIModel The SDK ships with utilities such as LoadSpec.exe and BBMetalWeb.exe.  What additional utilities would you like to see shipped with your SDK?  How would you use them?  Why are they needed? Their proper documentation is required
I would like to see some kind of an UnLoadSpec type tool. Development databases can sometimes get bloated with unused specs.
We should have unload utility which can remove particular spec from BBEC database. If you mistakenly load some specs in client machine there should be a mechanism in BBEC to remove unnecessary specs.
I use loadspec all the time, but it would be nice to be able to have several configuration sets for loadspec available so I can change between installs easily
Need to include the batch generator, business process generator
Spec Helper utilities would be really nice, but they are currently not in a state where they could be shipped. Many are buggy, etc. But, the Spec Finder would be especially helpful for clients since they would be able to search for existing specs so they don't repeat work, etc.
Just make my "refresh UIModel" work.
UIModel refresher? SDK Utility Additions and Improvements If there were a convenient way to script configuration changes into an spec, whereby a utility could be pointed at a customized page and generate an script that shows how their shell changes deviate from the out of the box version. This script could then be applied to the package spec and allow configuration changes to be succinct with customization deployments. When customers must migrate their environments from dev>testing>staging>production, this would be a major time saver for them, and would ensure a consistent deployment model across environments that included configuration changes made using design mode/shell designer.
Get rid of tabs and weird line endings in some of the code-generated templates.
Design view editor should contain more editing options like search etc.
A utility to generate and assign GUIDs for elements like Tabs, Sections etc should be provided, so that new GUIDs can be generated with ease and GUIDs do not get duplicated due to human error. This utility should check the spec for any duplicate GUIDs in database and Warn/Replace the GUID.
We shouldn't need that many utilities. I would like to just compile some code and have it work. SDK Utility Additions and Improvements - Continued
Full transcript