I'm working as a technical writer on a software project where there are three related documents: a user guide, a Python API reference and a C++ API reference.
The user guide describes how to use the classes, methods, and so on and then links to the API reference documents to make it easier for the user to find the detailed API descriptions.
I'm faced with the problem of how to layout the links to both the Python and C++ APIs in the user guide text. The API elements have the same names in both APIs.
I cannot find any information on this, but I've considered:
- Refer to the element name as text and then have links to each API in brackets. For example:
temperature(pythonLink, cppLink) gets the current value of the temperature.
- Include a link to one of the APIs in the element name and include a link to the other API in brackets. For example:
[temperature](cppLink) gets the current value of the temperature.
- In the introduction, state that all API links are to one of the APIs and that the user can refer to the other API document for more details. For example:
In the introduction: This guide only references the Python API. If you wish to use the C++ API, refer to the C++ API Reference document.
In the text: The function
[temperature]gets the current value of the temperature.
Are there any conventions/best practice for this kind of situation?