Re: Making a Software Documentation Polyglot
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
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads