Structuring Documentation

This is an example of how you can structure documentation for a complicated product.

In this case, the product — dubbed the Corporate Income Tax Framework — is an extension of SAP ERP software that is used to report taxes on corporate income. It allows developers to create local versions of corporate income tax reports that suit the users’ use cases and fulfil local legal requirements.

Skip the background and show the documentation or my takeaway.

Background

The product managers identified which parts of the process are unique, and which are the same irrespective of process or location. The parts that they decided were shared were these:

1. Listing of transactions that are related to corporate income tax and their amounts.
2. Calculation of totals of transaction amounts from step 1.
3. Additional calculations on totals from step 2, if necessary.
4. Output of legal forms with the results.

For example, this is how this list of transactions would be structured for a business:

• Revenue from sales
  • Revenue from sales of finished products
    • Revenue from main production activity
  • Revenue from sales of goods
• Extraordinary income

In this case, the revenue from sales was a sum total of revenue from sales of finished products and revenue from sales of goods, but separate from “extraordinary income”, which is everything else the company profits from, like interest on debt obligations.

Parts of the solution

The developers turned this business process into three high-level steps that we dubbed classification, settlement and reporting. This is what they’re for, in a nutshell.

Step	Step Description	Comment
Classification	Selecting transactions that already exist in the system as related to corporate income tax. Then, dividing them into classes, which is a way of organising corporate income tax items.	This step is unavoidable since financial transactions are not equal to corporate income tax items.
Settlement	Organising classified items into lists that will go into the tax form.	The lists in the tax form can be very complicated with multiple levels of depth, and their figures are sometimes calculated in a very complicated way.
Reporting	Creating and submitting corporate income tax forms.

Steps to prepare the form

For the SAP consultant, who is our key user, the process looks like this.

1. They maintain settings that allow the system to automatically classify the majority of financial transactions as they are entered into the system by the accountant.
2. They maintain settings that allow the system to calculate the corporate income tax values for the report.
3. They use an app create the structure of the future tax report form.
4. They maintain settings that allow the accountant to generate and file the tax form.
5. They use an app create custom form fields, if necessary.
6. They create end user operating instructions based on our documentation.

For the accountant, who is our end user, the process looks like this:

1. They enter financial transactions into the system using their usual workflow. The system classifies them in the background.
2. They use an app to check the classifications and change them if necessary. They can also create new ones, group them and do other stuff.
3. They use an app to prepare the tax form.
4. They print out the form and file or submit it electronically.

Resulting documentation

Link to the live version.

Here is how I chose to structure it. The navigation is based on the three parts or steps of the process. If the Miro embed does not work, click here for a JPG.

Takeaway

My contract expired before I could finish this. I still had to do quite a bit to make the documentation more readable, including an overview diagram or two, better short descriptions and navigation — there are some problems there. But I managed to do several things well.

Terms

With SAP, there’s always the struggle to go against the complexity of the process and to really focus on the actual needs of the user. This is because so much of the engineering process is product-based rather than user-based. With time, this gets into your head and so I struggled to move focus away from the product.

I think you can tell here. I still think that the term settlement is too ambiguous and can be replaced by something more obvious, like calculation, but I couldn’t convince all stakeholders. Their rationale was that it’s more complicated than calculation.

I did, however, manage to avoid adding other terms, and I simplified the wording on every screen as much as I could.

Clarity

This product is difficult to understand because it’s removed from real-world processes and therefore vague. I tried to remedy that as much as I could by:

• Focusing on real-world uses when talking about features
• Chunking the documentation properly
• Structuring the documentation

The next step would be to add an overview diagram to help visualise the various parts like I did in this post.

But, what I am reasonably happy with is the architecture: navigation, structuring, interlinking and short descriptions.