Warner writes, “Writing is thinking. Writing involves both the expression and exploration of an idea, meaning that even as we’re trying to capture the idea on the page, the idea may change based on our attempts to capture it. Removing thinking from writing renders an act not writing” (11). Because writing involves thinking and reflecting, our engagement in writing changes us. Warner says, “If writing is thinking — and it is — then it must be viewed as an act of our own becoming” (73).
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.
I'm continuing my analysis of my API documentation survey. I asked the following question.
What IDE do you use?
From 39 responses, here are the results:
The "Other" category included NetBeans, Android Studio, Java Studio, WebStorm, Visual C++, RStudio, PyDev, and PyCharm. Usually one or two participants indicated that they used these.
Analysis and interpretation
This turned out to be a great question, and it gives more context to some of the other questions, such as whether tech writers create doc by looking at the source code (60% said yes or sometimes), and what type of APIs tech writers document (78% REST, 41% Java and C++, 28% .NET).
What is an IDE?
IDE stands for integrated development environment. Programmers use IDEs when they write code. Just as a DITA author might use OxygenXML not only to write doc code, but also to validate it, catch errors, and compile the source into a webhelp output, developers use IDEs to do the same.
An IDE will flag an error before you compile and suggest ways to fix it. You can log messages to a console. You can compile your code into an output (such as a JAR file for Java). You can use debugging tools, export documentation (such as to Javadoc formats), see syntax highlighting, use shortcuts to add code, and more.
Text editors
A lot of people listed text editors such as Notepad++, Sublime Text, and Oxygen as the IDEs they use. I'm not sure why they put these text editors here, because most developers wouldn't consider a text editor to be an IDE (except maybe for JavaScript). If someone only listed a text editor, I counted this as "None."
An earlier survey question asked what type of APIs writers are documenting. Only about 40% are documenting Java, C++, or .NET APIs. This means the majority are documenting REST APIs, and as such, it makes more sense to use a text editor. However, if you're investigating Java source code through a text editor, to me this suggests that the foray into the code is superficial. If you're really playing around with programming code, you usually do so in an IDE so you can see it compile.
A lot of API doc writers play around with endpoints and various parameters, and use REST clients and browser plugins to test the calls, but this isn't really playing around in the source code. I don't consider an endpoint to be source code; instead the endpoint is controlled by source code that lives elsewhere.
The use of Visual Studio is a sign that writers are working with C#.
Why ask this question?
I asked this question because I was curious to know what IDE was most common. There's a lot of variety from one IDE to the next, and learning one is akin to choosing your favorite editor. Although many editors offer similar functionality, once you learn where all the buttons, menus, and other options are, it becomes comfortable to you.
I use Eclipse and like it quite a bit. Eclipse is extremely extensible, meaning it can accommodate a variety of languages and interfaces. You can use it for Java, C++, J2EE, and more depending on the perspective you download. It's free, open source, and has a lot of plugins available. Best of all, when I try to write code, it gives me helpful hints about ways to fix my code.
Eclipse has about 2/3 of the market share for Java IDEs:
Today it is the leading development environment for Java with a market share of approximately 65%.
--[Vogella](http://www.vogella.com/tutorials/Eclipse/article.html)
Takeaways
What are the takeaways here? If you're documenting a REST API, you're probably fine just using a text editor like Notepad++ or Sublime Text to look at code. But if you're documenting a platform API, you definitely want to use Eclipse for Java or C++, and Visual Studio for .NET.
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.
