Personal Insights
Leaving the Shire
In J. R. R. Tolkien’s The Lord of the Rings, Samwise Gamgee and Frodo Baggins left the shire on Sept 23 in the year 3018. That’s a good 17 years after Bilbo’s disappearance.
“If I take one more step, it’ll be the farthest away from home I’ll ever be” said Sam.
I had a moment like this of my own this year when I accepted a more design-focused role, to spend more time in a Minas Tirith frame-of-mind without losing sight of my quiet life back in Westron.
Departing from a 15 year sequestration comfortably scribing notes about HANA SQL in my hobbit-hole, I had to journey out to new lands, trekking through winding hallways and communing with distant races such as the wise Product Managers, the stalwart Partner Engineers, the graceful Marketers, and the lofty Chief Product Expert–all to acquire Insight.
While my ultimate quest was to learn more about the life and times of the legendary SAP users rumored to possess the arcane ability to develop custom/third-party solutions to access HANA data, my role on the journey was shifting imperceptibly from the grey area of Authoring to the clean white page of Designer.
I’d set out on a road to listen and learn about these heroes, their goals, their responsibilities, their pain points, and their hopes. Inspired, I’d returned with a better idea of what things were like out there (for them), and of how things could be (for them).
I still help document the SQL API, me and a small band of journeyers who know the value of good best practices like runnable examples, good templates, and Elevenses.
And like some Precious artifact that I fiddle in my pocket, I’ll never give up writing, anyway. But in 2020, I do mean to influence more at the Design level in all I do.
Not alone and not on my own strengths, but by listening first and last.
Hey, to that end…
What can the User Assistance team (those of us who write help content) do to improve the User Experience for custom/third-party developers?
Oracles within SAP – those who work directly WITH and for this persona — sure have some ideas. And I aim to implement a few! But I also invite insights from without as well. From you. Feel free to leave your own ideas below, or email me at my name (with a period in between) @sap.com.
What’s new in the SQL Ref guide?
Since I last posted, no new version of SAP HANA has been released. However, we did re-release a version of the SPS 04 SQL Ref guide with a lot of corrections (sorry about that) based on feedback we got from within and without.
Of course, if you are using ye old HANA Service (cloud), you’d want this version.
How about some Help Portal tips?
As always, a couple tips on Help Portal you likely wouldn’t know existed… because some things are only intuitive once you figure how to do them. 😉
Create a custom PDF
If there’s a chapter or a set of topics from various sections of a guide that you want to keep handy offline, you can create a custom PDF on the fly.
To do this, load the guide in Help Portal and use the Download the PDF widget to start things off. Then, use the left pane to choose your topics, and then finish by clicking the Create PDF button at the bottom of the selection pane.
TIP: There’s a max limit of 100 topics…
Save all or part of the table of contents (TOC) – as links
While super helpful for copying portions of to blog posts or emails, it is a little fiddlier to do. In fact, I hope it still works when you try it because it’s a bit of a hack.
- Open the guide you want the TOC for.
- In the URL field of your browser, replace ‘viewer’ with ‘doc‘ and replace the last long cryptic .html value with index.html.
For example:
becomes
https://help.sap.com/doc/4fe29514fd584807ac9f2a04f6754767/2.0.04/en-US/index.html
(If your URL didn’t have a long cryptic .html string at the end, just add the index.html directly.)
You should get a tidy HTML page version of the TOC like the one below, with the links indented to reflect their relationship to other content in the guide.
Feel free to contribute your own tips below and I’ll incorporate them in my next post as well.
What a nice "hello, back again!" from you, just before this decade comes to a close!
Great to learn that SAP doesn't let talented and engaged developers like you sitting in eternal twilight but push them into roles where they can help customers and users even better.
I've noticed some improvements with the documentation in SP04 - notably the listing of SQL standard feature compliance as well as the listing of database configuration parameters.
It feels like the documentation is really coming together and complete now.
Obviously, I still would love to see examples of how and when features can or should be used and when not to use them. I remember our email conversations about that and realize that this is probably never going to happen; but, hey, one can hope 🙂
Thanks again for all your great work, all the best for your new role and of course for the next decade.
Thanks, Lars - its great to hear from YOU. Hope you are well and happy where you are now?
Yeah, we finally were able to make a more public statement about compliance to the core features in the ANSI SQL feature. That was a lot of work for one of my colleagues product management.
The HANA Configuration Parameter reference is also extremely popular. I'm not really sure how folks found that info before centralizing it, but it's really handy now!
To your point about examples, I agree. This coming year we are investigating how we can develop more workflow-type documentation. More end-to-end, comprehensive info for a HANA feature. In particular, the top features that would really benefit from that sort of thing. Our efforts may also not be limited to documentation. Videos, tutorials, and maybe some sound blogs from stakeholder teams may factor in. It'll take time, and asking, and listening, and relying on experts...
Which Segues nicely here... given the depth and breadth of your SAP HANA expertise, what top features do you recommend we focus more on in this way? 🙂
Ok, since you're asking 🙂
My pet peeve is using databases effectively to achieve a goal.
In the context of programming "goal" can be relatively simple things like "computing the first business day after a given date" or "finding all employees that belong to a specific department" etc.
For such tasks, there exists plenty of material that shows how they can be implemented in SQL-based DBs if one is able to google for that.
If the HANA documentation could show proper examples of how to achieve these goals effectively with HANA (instead of trying to copy approaches that work on other DBs) I think that would be worthwhile.
Think of it as a kind of "how to do it with HANA"-catalog.
Adding in explanations of how the feature works and why it is the better way to do it that way in HANA and you've got yourself an awesome piece of manual.
Ideally, these examples would also consider the environment in which most HANA users develop applications: SAP on HANA, S/4, VDM and CDS views.
That way, the last step of "mental mapping yoga" is already done and developers can get right into writing good code for HANA.
Starting with hierarchy functions vs. recursive functions and date/time handling would probably cover many regular questions 😉
BTW: I just flipped through some pages of the performance tuning guide and it really is improving a lot. It's still very much based in "this is how the optimizer works" and does not cover a lot of the new HEX engine processing but it definitively is a step up from where it once was.
I hope you and your team keep on doing your good work and look forward to reading it.