Although I don’t work in road ecology or traffic engineering, the author somehow pulled me through 300 pages on this topic. He managed this not just through vivid language and diction, but by personally visiting places and telling stories about the specific challenges that animals, “carers,” forest service workers, and others faced as freeways and highways bisected and dissected their environments.
To use an analogy, suppose you’re a barista making espresso coffee. An AGI-capable robot trained as a barista is able to make all the coffee that a regular barista can make but twice as fast. Further, the Android barista can create exquisite espresso art in any shape that humans request, wowing them and making the experience novel. Soon the human barista is replaced. After all, the paying customer would rather pay $2.50 for a robot to make a latte instead of $5.00, especially when it tastes the same.
Most code samples in documentation are fairly basic, which is by design. Documentation tries to show the most common use of the API, not advanced scenarios for an enterprise-grade app whose complexity would easily overwhelm developers. (At that point, you end up with a sample app.)
With AI tools built directly into your authoring tool or IDE (such as VS Code), fixing simple doc bugs can become a mechanical, click-button task. Here’s the approach to fixing simple doc bugs:
(Note: The fact that I’m writing a book review on this topic might seem odd given that I usually focus on tech comm topics. However, I document APIs for getting map data into cars, so I sometimes read books related to the automotive and transportation domain. I also run a book club at work focused on these books.)
During the past few weeks, I’ve felt like my brain’s RPMs have been in the red zone. Granted, the constant stream of chaotic political news hasn’t helped—but regardless of current political events, I’m frequently checking the news, my email, and chat messages and operating in a mode that isn’t great. Reading long-form books has proven to be difficult. I run a book club at work focused on automotive and transportation books, and it took me two months to make it through a single book (granted, it was a 300-page historically dense book, but still).
“Biohacking” might be a pretentious cyber term for what is otherwise a straightforward experiment. For 10 days, I tracked my food and exercise levels while also wearing a continuous glucose monitor (CGM) to track my glucose levels. I then used AI to pair up the food + exercise with the glucose readings and perform an analysis about triggers for glucose spikes and recommendations to avoid them.
I want you to act as my AI stream journal (similar to a bullet journal), for the day. In this chat session, I’ll log 3 kinds of notes: tasks, thoughts, and events. Tasks are to-do list items. Thoughts are random ideas or notes I have. Events consist of food eaten, exercise, or descriptions of my internal states. The point is to have an easy way to dump all the scattered information in my head into a central log that you organize and analyze on my behalf.
To understand the documentation for Java APIs, it helps to see the context of what the documentation describes. As such, I created a simple little Java application (called sample-java-project) to demonstrate how the various tags get rendered into the Javadoc.
The sample Java project (available at github.com/tomjoht/sample-java-project) is a little Java application about different tools that a coyote will use to capture a roadrunner. There are two classes (ACMESmartphone and Dynamite) and another class file called App that references the classes.
This program only prints little messages to the console, but it’s simple enough to be instructive in its purpose. The purpose of the app is to demonstrate different doc tags, their placement, and how they get rendered in the Javadoc.
Clear the Use default location check box, and then click Browse and select the folder where you cloned the Github project. Click Open.
Import existing Java project
Click Finish to close the New Java Project dialog box.
The Java files should be visible in the left pane (Package Explorer) within your Eclipse IDE.
Eclipse File View
Play with the sample Java project
This Java app doesn’t do much. Its only purpose is to create some classes that demonstrate some Javadoc annotations. But for fun, run the app.
In the Package Explorer, expand javadoc_tags.
Double-click the App.java file to open it.
Click the Run App button :
Running the app in Eclipse
The main method (public static void main(String[] args) throws IOException), which appears in the App.java file, runs the functions defined in the other package’s files (ACMESmartphone.java and Dynamite.java).
publicstaticvoidmain(String[]args)throwsIOException{// First initialize your smartphone using the model number and license key.ACMESmartphonemyACMESmartphone=newACMESmartphone(2.0,"398978fdskj");// Locate the roadrunner.myACMESmartphone.findRoadRunner("Santa Clara","California");// Zap the roadrunner with the amount of voltage you want.myACMESmartphone.zapRoadRunner(40);}
You can view the details of each function by clicking the ACMESmartphone.java and Dynamite.java class files.
Then app prints this text to the console:
model2.0 now initialized for license 398978fdskj
location: Santa Clara, California
getting geocoordinates of roadrunner....
roadrunner located at Longitude = 39.2334, Latitude = 41.4899
Backfire!!! zapping coyote with 1,000,000 volts!!!!
Running the program
Side Note about Maven projects
Before leaving this intro topic on getting started with a Java project, I’d like to make a note about Maven. Java projects often have a lot of dependencies on packages that are third-party libraries or at least non-standard Java utilities. Rather than requiring users to download these additional packages and add them to their class manually, developers frequently use Maven to manage the packages. (Maven is to Java as Gradle is to Android.)
Maven projects use a pom.xml file that defines the dependencies. Eclipse ships with Maven already installed, so when you import a Maven project and install it, the Eclipse Maven plugin will retrieve all of the project dependencies and add them to your project.
The sample project doesn’t use Maven, but chances are if you’re getting a Java project from developers, you won’t import it in the way I previously described. Instead, you’ll import it as an existing Maven project.
(To import a Maven project into Eclipse, you would go to File > Import > Maven > Existing Maven Projects and click Next. In the Root Directory field, you would click Browse and browse to the Java project folder (which contains the Maven pom.xml file) and then click Open. Then you would click Finish in the dialog box. In the Project Explorer pane in Eclipse, you would right-click the Java folder and select Run as Maven Install. Maven retrieves the necessary packages and builds the project. If the build is successful, you will see a “BUILD SUCCESS” message in the console. You would then use the source code in the built project.)
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.
:
