Developer productivity means a lot to us, and in order to make it easier than ever for customers and partners to work with our software, we have kicked off a project last year to bring all the documentation in the Mobile Services product area together. Today, I am proud to announce that we released the
first version of our new consolidated documentation on the SAP help portal, alongside an
awesome new introductory video to Mobile Services. Feel invited to take a look for yourself, or read on to learn about the issues we faced in the past, the ideas behind the new documentation and the improvements we implemented.
Historically, each of our teams would own and write documentation as they saw fit: That makes sense based on the assumption that typically, readers of our documentation tend to focus on one platform - say, Mobile Development Kit - when working with our services and SDKs. However, having documentation spread out like this also lead to a bunch of awkward situations in the past: After all, the software and SDKs we build and distribute all revolve around Mobile Services features in one way or the other. Let's use the example of Push Notifications: Some of our tools provide bindings, i.e. platform-specific APIs, to consume push notifications on, say, Android and iOS. Others provide you with ways to easily write mobile-optimized back-end OData services, which in turn can trigger push notifications via business events. However, none of the previous tool-centric sets of documentation provided an end-to-end overview over Push Notifications: How they can be triggered, how they are processed by Mobile Services, and how client developers can use them to provide information to users. While the answer to those questions could be found scattered across the individual sets of documentation, we left it as an exercise to the reader to piece together the bits of information and to form an overview. I believe this also showed in various customer interactions I had over the past few years: In some cases, I was surprised how some of our features were misunderstood, and I argued that it must be the way in which we explain things that lead to confusion when looked upon from an outside perspective. For this reason, we began to analyze the assets we published and to think about ways in which we could make our authoring more digestible last year.
I guess every technical person has, at some point, heard of Conway's Law: "organizations which design systems ... are constrained to produce designs which are copies of the communication structures of these organizations." For that reason, it stood to reason that the way in which we create assets might not be ideal. I found that previously, we created documentation in a way that I jestingly like to call a game of Chinese Whispers: Developers would write raw guides or reference content in some way, which would then be sent to a User Assistance expert for editing and polishing. The resulting document is published on help.sap.com, and we're good. Or are we?
What struck me as odd was that there is a certain distance between the content expert - the developer - and the published asset. I have been meddling an awful lot in Open Source, and therefore I am used to working with documentation that has been written by the developer, and that was meant to be used by other developers. Typically, when something doesn't work or isn't explained, you'd open an issue and get direct feedback, and as a consequence the documentation is updated to avoid the issue from reoccurring. This kind of feedback loop doesn't work with our approach. Moreover, it is naturally difficult for an editor to tell if the information given is sufficient for the intended target audience: After all, they are editing experts, not product experts, which made me realize that we need to involve different perspectives in our content creation process.
In the end, we decided to pursue an inner source approach, in which the documentation will be rewritten in Markdown and managed in a central Git repository to which all teams contribute. Not only does it make the review more transparent and trackable - we now use pull requests instead of mail threads - , it also makes it easy to involve other people from our organization, such as the person originally requesting a feature, in our content review. Then there has been a bunch of other issues that we weren't happy with: For one thing, the content structure seemed to us like it wasn't meant to help customers achieve a goal, but to describe the structure of our tools - libraries, components, APIs. For another, we represent the Mobile strategy of the entirety of SAP, yet I felt our help content could be better mobile-optimized. Last but not least, each team had a slightly different approach to writing docs, which made it difficult for readers to move from one set to another and to easily find similar information.
Fast forward a few months: We have implemented an entirely new content structure and theme for our documentation that seeks to address all these issues. Automated checks ensure consistency and correctness for each team, and since content is side-by-side, it is easier than ever to align newly created content with what we already have.
But this is not where we stop - the current release only marks the first milestone for us to show how much our community matters to us. We still are in the process of migrating all content, most notably SAP Mobile Cards, SAP Mobile Development Kit, and SAP Cloud Platform SDK for iOS, and to redirect from our old to our new documentation. Also, the current documentation is only available in English, and we are working hard to provide translated texts for other languages as soon as possible. Once this is done, we have a long list of additional content that we want to provide, that we feel hasn't been properly addressed in the past.
And last but not least - since I mentioned Open Source - we are looking for ways to open up our documentation for external contributions. Of course, that doesn't mean that we mean to put less effort into writing and editing content because we hope others will fix it. But people reading and using our documentation to build great software are likely among the first to stumble across content gaps, unclear phrasing, or other issues, and with our new tooling and internal processes, we want to make it as easy as possible to provide feedback and to get content issues resolved in a more direct and modern way.
Stay tuned for updates on this project, and feel free to share your thoughts in the comments!
Update 2020-04-14: Updated video link
