Skip to Content
Technical Articles
Author's profile photo DJ Adams

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. 

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:

The%20Contribution%20Guidelines%20documentation%20on%20the%20SAP%20Help%20Portal%2C%20with%20the%20Edit%20and%20Feedback%20buttons%20highlighted

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:

The%20Markdown%20file%20representing%20the%20documentation%20page%20content%20on%20GitHub%2C%20with%20the%20Edit%20button%20highlighted

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:

The%20documentation%20page%20Markdown%20content%2C%20in%20edit%20mode%20on%20GitHub

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:

Hands-on%20SAP%20Dev%20live%20stream%20title%20picture

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!


Further reading

Collaboration missions for the Open Documentation Initiative

Assigned tags

      37 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Denys van Kempen
      Denys van Kempen

      Excellent initiative

      Author's profile photo Mahesh Kumar Palavalli
      Mahesh Kumar Palavalli

      Awesome Initiative!! I like the new UI and its responsiveness. I hate old SAP help on many levels; at times I felt like breaking my laptop because of its slow response. It's quite refreshing to see the new UI, and I am super happy about this:)

      Author's profile photo Daniel Wroblewski
      Daniel Wroblewski

      Second that ... looking forward to contributing 🙂

      Author's profile photo Antonio Maradiaga
      Antonio Maradiaga

      👏👏👏👏 without a doubt this is the right direction for SAP docs. Looking forward to contributing to it!

      Author's profile photo Julia Russo
      Julia Russo

      🎉🎉🎉🎉🎉🎉🎉

      Author's profile photo Iwona Hahn
      Iwona Hahn

      👏 🤝

      Author's profile photo David Ruiz Badia
      David Ruiz Badia

      Awesome!

      👏

      Looking forward to contributing to it!

      Author's profile photo Christian Lechner
      Christian Lechner

      Finally - definitely a move in the right direction!

      Author's profile photo Luis De Azevedo Freitas
      Luis De Azevedo Freitas

      There is a long way to go to, but that is definitely a good start. Documentation has its own lifecycle pace , which I am confident the community will be of great help. Kudos! 🙂

      Author's profile photo Nabheet Madan
      Nabheet Madan

      Amazing step in the right direction #BeOpen

      Author's profile photo Marco Beier
      Marco Beier

      Awesome! What a huge step, looking forward to contribute. 🎉🎉

      Author's profile photo Dell Stinnett-Christy
      Dell Stinnett-Christy

      Please tell me that you'll be opening up the documentation for the BI Platform sometime in the near future - that developer documentation needs some major updates!

      Author's profile photo Sven Gierse
      Sven Gierse

      Over time we aim to get all of the SAP BTP documentation ready for collaboration. Give us some time to gain experience with the pilot and to define our scale-out roadmap.

      Author's profile photo Kenneth Murray
      Kenneth Murray

      Liking the idea of this!
      Just be consistent and be sure to add valid context and USEFUL examples with EVERYTHING.

      Only really good documentation I remember was I believe the CL language on AS400.
      Best of luck and hope to contribute to this effort!

      Author's profile photo Stefania Santimbrean
      Stefania Santimbrean

      This is really nice! Looking forward to seeing this possible also for other documentations 🙂

      Author's profile photo Arnold Spaeing
      Arnold Spaeing

      Good to see it embarking!
      But why not calling it "Open Help Initiative"?
      Documentation sounds old-school and misleading in regards of providing relevant information for the user. You might document a lot of information, but what makes it helpful for the audience?

      Author's profile photo DJ Adams
      DJ Adams
      Blog Post Author

      Thanks!

      My take on your question - it's because it's about the documentation and how our collaboration focuses around that content 🙂 I don't see "documentation" as sounding old school - quite the opposite, in fact. With changes in technologies and techniques happening even more frequently these days, documentation is more important than ever.

      We should be celebrating and working together on documentation in the same way we do that for code.

      cheers!

      dj

      Author's profile photo Pinaki Patra
      Pinaki Patra

      That's a great leap in opening up future possibilities !!

      Author's profile photo Daniel Wroblewski
      Daniel Wroblewski

      You should have made some mistakes in those 2 documentation sets so we'd have a reason right away to contribute ... or maybe you did !!??

      Author's profile photo DJ Adams
      DJ Adams
      Blog Post Author

      Haha, great minds, etc 🙂 I did leave one, but it was already tidied up 🙂 I'm sure I can find others, let's see ...

      Author's profile photo Marc Van Driel
      Marc Van Driel

      Great initiative, looking forward to contribute. This will improve the overall quality of the SAP documentation even more.

       

      Are there any plans of making this available as a solution to create our own documentation?

       

      Author's profile photo DJ Adams
      DJ Adams
      Blog Post Author

      Thanks Marc. To your question - this initiative doesn't have that as a goal right now, no - the core focus is collaboration on content.

      Author's profile photo Amaury Van Espen
      Amaury Van Espen

      Such a collaborative/collective intelligence project !

      Author's profile photo Bernhard Luecke
      Bernhard Luecke

      Great initiative - something we from SAP Support are looking forward to and contribute to!

      Author's profile photo Stefan Haag
      Stefan Haag

      I would like to have a space below each documentation text, to add web links to any available related webpage (blog, wiki) which describes that related feature within an process or "How-to" setup.

      At SAP Community Home there are so many good blogs, bringing a "boring" feature documentation into a process context.

      In other words:

      1. leverage what already exists might be the QUICK-WIN and
      2. in addition collect feedback about documentation which requires improvements by SAP documentation experts.
      3. and finally, enable everyone to add know how to an existing SAP Help page.
      Author's profile photo Jaime Rodríguez Capote
      Jaime Rodríguez Capote

      This is really great, I like how SAP is becoming more and more open!

      Author's profile photo Marco Büscher
      Marco Büscher

      Cool

      Author's profile photo Bärbel Winkler
      Bärbel Winkler

      I gave both the "provide feedback" as well as the "edit" options a try today and from what I can tell, this worked nicely and as it should. One interesting learning: even if one doesn't really know the topic of the help page well or at all, one can still provide apparently helpful feedback as far as wording or typos are concerned.

      What I'm however wondering is this: as more people get involved with improving the pages, how easily will "back-and-forth" changes or submitting similar issues be prevented? When clicking on "feedback", you immediately get directed to the page for creating a new issue. Unless one remembers to check and scroll through the already raised/closed issues in a separate tab, you'll not really know if somebody else already submitted the same or similar feedback. Is there a means to easily and ideally automatically check for potential duplicates before the issue gets created?

      Cheers

      Bärbel

      Author's profile photo DJ Adams
      DJ Adams
      Blog Post Author

      Thanks Bärbel! We appreciate you giving it a go, and I can also see you have one of the mission badges to show for it - kudos 🙂

      Baerbel%20s%20badges

       

      Your question is a good one; at the end of the day, it will be a nice problem to have (and that's what we're working towards - a wealth of collaboration). There isn't any automated way to check, and from a programmatic perspective, while there may be a way of checking if multiple pull requests (for content contribution) were acting upon the same help text, there wouldn't be an easy way to do the same for issues (feedback provision) as it's more free-form.

      But that's then the job of the triage role here internally, to check if a new feedback item duplicates older still active items. And we have the duplicate label to highlight and manage anything like that.

       

      Author's profile photo S Abinath
      S Abinath

      good intiative

      Author's profile photo Markus Perndorfer
      Markus Perndorfer

      I cannot upvote this initiative enough!

      Author's profile photo Pieter Janssens
      Pieter Janssens

      Hi DJ,

      Please also consider a more open document approach to @sap NPM packages.

      If lucky the package contains a reference to the proper official support channel (e.g. @sap/approuter), but it's not ideal to create support incidents for documentation improvements/corrections.

      There are however, also many @sap NPM packages that don't reference any support channels (e.g. @sap/xsenv, @sap/logging).

      Best regards,

      Pieter

      Author's profile photo DJ Adams
      DJ Adams
      Blog Post Author

      Thanks Pieter. I'll share that feedback internally 👍

      Author's profile photo Purushottam Aher
      Purushottam Aher

      Great initiative!!

      Author's profile photo Sonal Sharma
      Sonal Sharma

      Great Initiative!!

      Author's profile photo Amaury Van Espen
      Amaury Van Espen

      It looks great, thank you for permitting us to contribute and maintain documentation =)

      Such a gamification for this initiative ! Nice =) Let's contribute and take part in this initiative to enhance and mobilize locally.

      Author's profile photo Jasmin Weis
      Jasmin Weis

      Awesome! 👏