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.
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.
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!
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.
Collaboration missions for the Open Documentation Initiative
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:)
Second that ... looking forward to contributing 🙂
👏👏👏👏 without a doubt this is the right direction for SAP docs. Looking forward to contributing to it!
Looking forward to contributing to it!
Finally - definitely a move in the right direction!
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! 🙂
Amazing step in the right direction #BeOpen
Awesome! What a huge step, looking forward to contribute. 🎉🎉
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!
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!
This is really nice! Looking forward to seeing this possible also for other documentations 🙂
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?
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.
That's a great leap in opening up future possibilities !!
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 !!??
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.
Such a collaborative/collective intelligence project !
Great initiative - something we from SAP Support are looking forward to and contribute to!
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:
This is really great, I like how SAP is becoming more and more open!
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?
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 🙂
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.
I cannot upvote this initiative enough!
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).
Thanks Pieter. I'll share that feedback internally 👍
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.
This will be the future documentation for SAP Products and this will also help in revising in case of any new update..!! Awesome! 👏
HI D J ADAMS , this is an excellent initiative , to learn , to grow. It helps to gain knowledge about product features more while updating the documentation when new features got added to the product
Just posted my Feedback for "What to Expect" #84 on Github.
Awesome idea. SAP Open Documentation Initiative. more collaboration.