Introducing the Open Documentation Initiative

We want to collaborate with you to improve our documentation. To do this, we’re taking our first steps with the Open Documentation Initiative. 

See the Updates section for new information.

One of the things I’ve been happy to observe over the decades is SAP moving towards an increasing openness. To name just a few milestones, there’s the inclusion of open protocols such as HTTP in the early days, the myriad and ongoing contributions to open source projects, the adoption of the open data protocol OData, the establishment of our Open Source Programme Office, and the open sourcing of UI5.

Moreover, I’ve been excited to see the growing use of collaboration platforms such as GitHub, where we have our tutorial content and plenty of sample code … and of course GitHub is the home of our open celebration of coding and collaboration & what makes us developers – Devtoberfest.

So now it gives me great pleasure to introduce SAP’s Open Documentation Initiative.

What it is

Collaboration is at the heart of many good things, and helps strengthen trust between participants. Our documentation on the SAP Help Portal is a significant meeting point between SAP and customers, partners & individuals, and successful collaboration at that meeting point can pay dividends for all involved. Know-how, plus experience in the field, is a powerful combination.

Our aim is to take the first steps towards making the documentation process more collaborative, by inviting you to provide feedback and contribute content.

Looking at some documentation and you’re not sure that it’s quite hitting the mark? Send us some feedback and start a conversation in the form of an issue.

Found something that doesn’t look quite right, and you know how it could be addressed? Contribute a small piece of content, and start a conversation with us in the form of a pull request.

We’re bringing the content to you, in the form of Markdown resources in repositories on GitHub, where we can all benefit from standard issue and pull request workflow mechanisms that are used in countless collaborative processes.

This announcement marks the beginning of a journey, with some small steps in the form of a pilot programme. That means, from the outset, only a very limited subset of SAP documentation will be included in this initiative. This will give us the best chance of making a success of things.

The pilot programme

We’re taking some early steps with two relatively small documentation sets, and have a further documentation set ready and waiting to roll in at some stage in the near future too.

First, there’s the documentation for the SAP Business Application Studio. This will be no doubt familiar to many of you, and that’s one of the reasons we picked it.

We also have a set of guidelines that describe how you can contribute. These are the Contribution Guidelines, and these guidelines represent the second documentation set that is open for collaboration. (If that’s not meta, I don’t know what is!)

A brief overview

Here’s a brief overview of what to expect.

First, when browsing a page in either the SAP Business Application Studio documentation or in the Contribution Guidelines, you’ll notice a couple of buttons along the top bar.

Here’s an example:

Via the Feedback button, you can provide feedback on the page content, either generally or specifically. This feedback provision will be via a GitHub issue.

Alternatively, if you find something for which you want to offer some content contribution, you can use the Edit button. This will take you to the Markdown content for that page, in the repository for that documentation set, on GitHub. We have a new organisation there, SAP-docs, which will be the home for the Markdown content and collaborative processes in this initiative.

Here’s what that content will look like:

Then, when you use the ✎ button on this page, it will launch the online editor, where you can make your change suggestion, and follow the standard GitHub workflow process based on the automatic creation of a pull request.

Here’s what edit mode looks like:

Of course, if you’re comfortable with GitHub and git processes, you can also make your modifications and suggestions locally and push them to your fork and then make a pull request, in the normal way, if you prefer that approach.

Learn more

There are a couple of ways to learn more.

First, there’s those guidelines I mentioned earlier. Head on over to the Contribution Guidelines on the SAP Help Portal and have a read through them, it shouldn’t take more than a quarter of an hour.

Then we have a Hands-on SAP Dev live stream episode planned, for Friday 28 May at the usual Friday time of 0800 GMT:

You can join live and walk through the process with me, ask questions, chat with fellow live stream viewers, and learn how easy it is to get involved in the collaboration process. The live stream is automatically recorded, so if you can’t make it, you can watch it on our SAP Developers YouTube channel at a time that suits you.

Get ready

To get ready, make sure you have a GitHub account (they’re free, and easy to set up) and then familiarise yourself with the Contribution Guidelines process.

If you have any questions or issues with the process itself, you can raise an issue on the Contribution Guidelines repository directly using this issue template that has the ‘meta’ label assigned. Note that this is for when you want to create an issue about the process itself, as opposed to an issue about documentation content.

These are early days, and we’re looking to you, the SAP community, to help us make this collaborative initiative a success. Thanks!

Updates

Since the publication of this post, there have been some updates:

27 May 2021 – read about the Collaboration missions for the Open Documentation Initiative

29 Nov 2021 – more documentation covered – see SAP BTP Documentation Goes GitHub – New Collaboration Process

10 Mar 2022 – Contribute to the Setup Guide for SAP Cloud ALM

04 May 2022 – Collaborate with us on the Migration Guide for SAP Process Orchestration!

28 Jul 2022 – New video SAP BTP Documentation Goes GitHub: Learn About Our New Collaboration Process

10 Oct 2022 – more documentation sets added – see Join forces with us and collaborate on the SAP Custom Domain Service guides!, Spotlight: SAP HANA Cloud supports the SAP Open Documentation Initiative and Collaborate with us on SAP BTP, Neo Environment Documentation.

09 Nov 2022 – two more documentation sets added – see Identity Authentication Opens Its Documentation for Your Feedback with GitHub and Collaborate with Us – Open Document Initiative for SAP Integration Suite.

Further reading

Collaboration missions for the Open Documentation Initiative