3

Background

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.

Problem

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:

  1. Refer to the element name as text and then have links to each API in brackets. For example:
    The function temperature (pythonLink, cppLink) gets the current value of the temperature.
  2. Include a link to one of the APIs in the element name and include a link to the other API in brackets. For example:
    The function [temperature][1] (cppLink) gets the current value of the temperature.
  3. 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][1] gets the current value of the temperature.

Are there any conventions/best practice for this kind of situation?
[1]: https://link

1 Answer 1

1

So a common technique I have found is for online or digital documentation, to offer the information for the different languages as a selectable dropdown or tabbed panel in some way. Either as a tabbed panel around the language specific content (everytime there is language specific content) or as a selector at the top or something that lets you pick the language.

Two real-world examples are:

  1. For the tabbed panels for the content: Selenium's Online documentation Excerpt from Selenium documentation showing the tabbed panel to select the programming language for that part of the page
  2. For the selection for the whole document to be changed: BrowserStack's Online Documentation (In their case they even let you choose which framework in the language) Excerpt From BrowserStack's documentation showing the drop down in the left sidebar where the programming language can be selected

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.