Re: Making a Software Documentation Polyglot

Subject: Re: Making a Software Documentation Polyglot
From: Monica Cellio <techwrl -at- cellio -dot- org>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 01 Feb 2022 12:39:18 -0600

In our case, our software documentation (mix of concepts and tutorials) has been targeted to Java developers. But as we grow, users from other programming languages also have started to use our product. So, we want to make the content of this documentation language-independent, but having difficulties in starting the journey.

When I joined my current company we had a C++ API and a smaller Java API. The developers had kept the class and method names the same between them, presumably for ease of porting. Later these were joined by Python and R APIs; R is rather different in details, and some of the Python API follows Python norms rather than C++ ones.

I inherited separate doc for C++ and Java with a lot of cut/paste. In addition to the maintenance challenges (even with shared includes), it caused some problems for our search. A few years ago I reorganized the doc to move general concepts "up", for example talking about how to write a parser and what the process() method had to do and so on, and added per-language subsections with API details and examples. More recently we worked out how to do in-page tabs with our tools, so we can now show the different languages' APIs in-page along with the higher-level discussions.

Here's an example topic: https://www.vertica.com/docs/11.0.x/HTML/Content/Authoring/ExtendingVertica/UDx/ScalarFunctions/ScalarFunctionClass.htm

Monica
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | https://techwhirl.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


Previous by Author: RE: The Bank
Next by Author: Making a Software Documentation Polyglot
Previous by Thread: Re: Making a Software Documentation Polyglot
Next by Thread: Re: looking for HTML link checker


What this post helpful? Share it with friends and colleagues:


Sponsored Ads