sap pi documentation survey 2010 - home - · pdf filesap pi documentation survey page 4 method...

SAP PI Documentation

Survey 2010

Daniel Graversen

Figaf ApS

SAP PI documentation survey

Contents Summary ............................................................................................................................................................ 3

Method .............................................................................................................................................................. 4

Creating documentation .................................................................................................................................... 5

When do you create the documentation? .................................................................................................... 5

How much time do you spend on documenting an interface? ..................................................................... 5

Do you learn anything about your interface/scenario while you document? .............................................. 6

What types of documentation do you create? ............................................................................................. 7

Do you document based on… ........................................................................................................................ 7

Is documentation of PI interfaces useful? ..................................................................................................... 8

Usage of the documentation ............................................................................................................................. 9

Who is the audience of the documentation? ................................................................................................ 9

When do you use the documentation? ......................................................................................................... 9

Is there other information around documentation that you would like to share? .................................... 10

Conclusion ....................................................................................................................................................... 12


Summary Figaf has performed a survey regarding how people document their SAP Process Integration (PI) or

Exchange Infrastructure (XI) interfaces. Sixty people were surveyed with an average of 4.5 years of

experience.

The good news is that 49% found that the process of creating documentation made them learn something

new. Also, 92% found that the documentation was valuable. Documentation is either based on an interface

or a scenario. There was approximately 50% for each type.

Documentation is mostly used by developers and supporters, but it also used by many other types of users.

The documentation is most often used for learning about the interface and to signal changes in the project

phase.

It was suggested that people needed a new template for creating templates. Also a large number requested

an automatic tool for documenting SAP PI.


Method The survey was performed by e-mailing a questionnaire to a list of people; LinkedIn was used to

obtain responses. The responses were collected in August and September 2010.

There were 60 responses. Of these, 54 were consultants and 6 were in-house developers. The

average experience with SAP PI is 4.5 years. That is significant, since the product is 6 years old.

Therefore, the participants do have a lot of experience in the field. The distribution of replies is as

follows:

There has not been any correlation between the experience and the consultant type towards each

answer.

For the free text areas in the survey, the most dominant answers are summarized. The most

dominant answer is at the top.

The survey was grouped into two categories. One category pertains to the creation of the

documentation and the other is about the usage of the documentation. The two categories will be

described in the next sections.

After the survey was evaluated, it became clear that it would be useful to ask even more

questions. It did not seem feasible at the moment. It would be interesting to ask these questions

at a later stage of the process.

0

5

10

15

20

25

1 2 3 4 5 6 7 8 10

Nu

mb

er

of

resp

on

ses

Years of experience

Years of SAP PI/XI experience

Total


Creating documentation The following question was asked to determine how the creation of the documentation was performed.

When do you create the documentation?

Most of the developers start with the documentation. The primary reason is to make the

functional description happen in the interface. Forty-eight percent start documentation before the

development is performed.

It was only possible to select one of the actions. If the primary documentation is performed before

the development/implementation, the documentation does not reflect what is implemented.

It is quite comforting that everybody is documenting. It makes a lot of sense.

There is a split with around half doing the primary part before development starts and the rest do

the work after the development has begun.

How much time do you spend on documenting an interface?

As some people responded this depends on the interface. People have probably responded with

their best guess for the mean. The average number of hours is 6, which is quite a bit of time if

there are several interfaces.

The distribution is similar to the following.

48%

27%

25%

0%

When do you create the documentation

Before the development

After development but before Test

After test

I do not document


Most people spend two to eight hours on documentation of the interfaces. If this is just on the

technical description, the numbers do make a lot of sense. If this also covers the documentation

before, then it is much lower than expected.

Some interesting responses were around 10% or 20% of the total development time. If those

numbers are correct, then the documentation is a large part of the development process.

Based on the response the amount of time spent documenting an interface is not trivial.

Therefore, it is something that should be taken into account when setting up the development

process.

Do you learn anything about your interface/scenario while you document?

It is quite interesting to learn that if creating the development process results in additional

knowledge. In 49% of the responses, people learned something new about what they did to create

the documentation. This is quite interesting and makes it a much better concept to create the

documentation.

The top responses are as follows:

Naming conventions become clear

Understand the project

Gets a good understanding of the interface

Compares towards requirements and missing fulfillment of requirements, error handling,

loopholes, etc.

Get clearer on the business requirement

Learn about the process, which may have been created by others

Find better ways to implement the interface process

0

2

4

6

8

10

12

1 2 3 4 5 6 8 10 12 15 16 20

Re

spo

nd

s

Number of hours

Hours pr interface


So the development process is valuable and not just something that is done to fulfill a

requirement. Therefore, it makes sense to work on the documentation.

What types of documentation do you create?

What are the most common forms for documentation? It is possible to have more responses in

this survey. Since there were 60 responses, everyone was creating the technical documentation.

But there is also an astonishing 50 (or 83%) who know how to create a mapping documentation.

It would be really nice to know if the other documentation in the Mapping, Technical and

Functional specification also included the other parts of documentation. It would have been nice

to know the distribution of the documents.

Nearly half of the respondents also create support documentation. This is a high number

according to our expectations. It is an important document because it facilitates a quick resolution

of the problem.

Do you document based on…

One interesting question is what the documentation is based on. Is it based on the interface or

scenario? Half responded with interface, and the other half said the scenario.

There may not be a large difference between the two instances. But the interface is focused on

point to point, while the scenario is more focused on the full flow.

0 10 20 30 40 50 60

Functional specification

Technical specification

Mapping specification

Process or BPM documentation

Reference or support document

User documentation

Other

Number of responses


In conversation we also learned about the use of models as a form of service documentation. The

models will provide a way to start developing in a much more service oriented order.

Is documentation of PI interfaces useful?

It seems that most of the respondents (92%) found that the documentation provides value. It is

therefore a process that makes sense to improve because it provides value.

Interface50%Scenario

43%

Other7%

Documentation based on

No just wast of time7%

Yes, it provides value92%

Other1%

Does documentation provide value


Usage of the documentation The second part of the survey was to determine what the documentation was used for.

Who is the audience of the documentation?

When writing documentation it is important to understand who the target audience is. If the

documentation does not match the target audience, it may be wasteful to create the

documentation. It will also be much more difficult for the readers to understand the

documentation if it does not match what has been written.

They result from the survey is:

It is quite interesting that over 75% of the respondents create the documentation to help with

error handling, support and other developers. It is probably the most used scenario of

documentation. Therefore, a good documentation must fulfill all these three groups.

Documentation is also created for the business in 46% of the responses. This signals that the

business needs to understand what the documentation is about. It also signals that the PI is

something that the business needs to worry about. Therefore it may be important for developers

or creators of the documentation to have some business knowledge.

Other types of documentation are End 2 End, Unit test documents (mapping changes) and

Regression test documents.

When do you use the documentation?

There are a number of different things the documentation is used for. The main groups of answers

were in these categories:

To learn about the project and the interface that needs to be solved

In all the phases of the project, and to signal the change in phase blueprint/-

implementation/test/go live.

To transfer knowledge between teams, especially with off-shore teams.

0 10 20 30 40 50 60

Developers

Business

Support

Error handling

Other

Number of responses

Target Audience


Have conversations with the business around mappings of documents

Keep track of status and issues in connection with the document

It is mostly for the customers’ knowledge

For sign-off on the project and hand-over to the production.

For support error handling

Verification of the mappings

Update that there are any changes in the document.

These responses give a good understanding regarding when documentation is used. Most of the

responders were to support and transfer knowledge. That is the major reason why people will

spend time on documentation, so it is expected that it is the most frequent usage of

documentation.

Other findings

This section is a summary of all the extra questions asked that did not fit into the categories of creation and

usage of the documentation.

Is there other information around documentation that you would like to share?

This was very valuable. The list includes the following questions.

There is requested a new template for documentation PI scenarios because there only was

one with the ASAP methodology. It would be nice with a generic set of templates to use

across clients.

PI should have a documentation feature so the documentation could be created on the fly.

The key is to get a tool that can extract data in a readable form for people without PI

experience.

Some technical documentation tends to be a copy of the settings.

Ground for knowledge transfer session prior to go-live

The naming conventions are quite important for some users to understand.

A way to document message mappings while in mapping tool.

There may be a difference in what the client requests of documents because they might

not have the knowledge of what needs to be in the documentation.

One person pointed out that migrating from a business connecter without any

documentation is a pain. Remember to document so the people after you can understand

what is going on.

Documentations do not need to be long. Only when the interface gets complex.

Most people responded that they wanted a template for creating documentation. There was a

documentation template with the SAP package. It does not look like the document has been

updated to fit SAP PI. The main benefit would be to have a template that everybody used. So

when you got to a new client it would be easy to understand what he or she was working on.


Shameless Plug: Figaf has created a template for documenting and it is available at

http://www.piarchitecture.com/sap-pi-documentation-template/ for only 97$. This template is

one that I, Daniel Graversen, have been working on. It is based on what I have seen to be most

useful for the developers and also the support organization. The document targets the functional

documentation and the support documentation. The document is based on the philosophy around

scenarios. If the scenarios are used, then there is no reason for linking all the objects that are a

part of the system.

http://www.piarchitecture.com/sap-pi-documentation-template/


Conclusion The survey revealed some quite interesting aspects of the usage and creation of documentation.

It takes an average of four to five hours to create documentation, though this timing may be

varied.

It is quite interesting that people find the process of creating documentation as a valuable phase.

The reason is that 49% learned something new while they created the documentation. They

learned about the project, the naming convention and got a better understanding of the project.

Everybody creates a technical specification, and 83% create a mapping specification. Sixty-six

percent create the functional specification. So there are many documents that are created to

ensure the documentation is produced correctly.

Fifty percent of the documentation is based on the interface, while 43% is based on the scenarios.

Using the scenarios makes it much better to get an overview of what is happening and how the

interfaces are connected.

The audience of documentation is mostly developers, followed by the support organization.

The documentation is used to learn about the project/interface. Documentations are also used for

the hand-over between the different phases in the project and also as knowledge is transferred

between different persons.

One thing that people frequently mentioned is that they miss a standard SAP Template for

documentation. There are a number of different templates out there, but everybody has their own

instance of the documentation.

A requested feature was also to have some tool to automatically create the documentation.

sap pi documentation survey 2010 - home - · pdf filesap pi documentation survey page 4 method...

Documents