Skip to Content
Technical Articles

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

27 Comments
You must be Logged on to comment or reply to a post.
  • 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:)

  • 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! 🙂

    • 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.

  • 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!

  • 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?

    • 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

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

  • 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?

     

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

  • 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.
  • 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