Current trends and opportunities in API Documentation
API Documentation: Trends and Opportunities
Rajeev Jain (M.Sc., M.B.A.)
Rajeev Jain (M.Sc., M.B.A.)
Due to rapid growth in companies engaged in software product development, the volume of API documentation has increased considerably in recent years. API documents help customer to customize an application.
Good API guides help companies save a lot of money in terms of support services and companies have realized that they need the services of professional technical writers for API guides. Individuals responsible for creating API guides must be highly skilled in their ability to transform volumes of technical jargon into easy-to-follow end-user workflows.
The demand for API writers is increasing. To become an API documentation expert, you are not required to be a FrameMaker, RoboHelp, Doxygen, or JavaDoc expert. But you must have an analytical mind, basic programming skills, and a desire to explore and learn new technologies.
This paper includes the basics of API guides and also covers the topics, such as:
- current API documentation trends
- skills required to write API guides
- auto-generation tools available
- opportunities available for technical writers
- challenges
Introduction
Among the first lessons for technical writers is “Whatever you see, document it”. Technical writers are expert in documenting the things they see. But can you imagine documenting something:
- which you can’t see easily
- without any GUI
- without any screenshots
- written very systematically with limited number of words
- for which you need to brush up with programming skills
If yes, then get ready for the high salaries, as you could be among those who will be contributing as an application programming interface (API) writer.
API is an interface used by programmers to customize an application. It is an interface through which the user interacts with your software and in not user friendly.
Purpose
The purpose of this paper is to:
- create awareness for API writing
- look into the need for API guides
- discuss the API documentation process and contents required
- explore the current trend and practices followed to write API guides
- explore the skills and knowledge of tools required to master the art of API writing
- discuss auto-generation tools and their limitations
- explore the opportunities available for technical writers
Good API guides help companies save a lot of money in terms of support services and companies have realized that they need the services of professional technical writers for API guides. Individuals responsible for creating API guides must be highly skilled in their ability to transform volumes of technical jargon into easy-to-follow end-user workflows.
The demand for API writers is increasing. To become an API documentation expert, you are not required to be a FrameMaker, RoboHelp, Doxygen, or JavaDoc expert. But you must have an analytical mind, basic programming skills, and a desire to explore and learn new technologies.
This paper includes the basics of API guides and also covers the topics, such as:
- current API documentation trends
- skills required to write API guides
- auto-generation tools available
- opportunities available for technical writers
- challenges
Introduction
Among the first lessons for technical writers is “Whatever you see, document it”. Technical writers are expert in documenting the things they see. But can you imagine documenting something:
- which you can’t see easily
- without any GUI
- without any screenshots
- written very systematically with limited number of words
- for which you need to brush up with programming skills
If yes, then get ready for the high salaries, as you could be among those who will be contributing as an application programming interface (API) writer.
API is an interface used by programmers to customize an application. It is an interface through which the user interacts with your software and in not user friendly.
Purpose
The purpose of this paper is to:
- create awareness for API writing
- look into the need for API guides
- discuss the API documentation process and contents required
- explore the current trend and practices followed to write API guides
- explore the skills and knowledge of tools required to master the art of API writing
- discuss auto-generation tools and their limitations
- explore the opportunities available for technical writers
API documentationAn API is required to customize the working of an application. API guides are used by programmers and other professionals only. Sometimes, these guides are also used by students.
Skills RequiredThe basic skills required to master the art of API writing are:
- Ability to understand languages like C, C++, Java, VB.NET, etc.
- Basic understanding of programming concepts
- Ability to understand code, functions, methods, classes, etc.
- Ability to think like a programmer
The basic understanding of Unix or Linux operating system and the man pages
(help provided by Unix and Linux operating systems) will be an added advantage.
Current Trends
Generally, but not always, API documents are written by programmers and SMEs. Technical editors edit these documents for grammar, punctuation, and style-related issues. Finally, tools like Javadoc and Doxygen are used to generate the required output.
Until recently, the volume of API documents was not very high and since these documents were meant for high-tech professionals only, no one really bothered much about the overall quality. But the trend is changing and companies have realized the importance of the presentation and overall quality of these guides. This change provides an opportunity to all technical writers. For this, we must update ourselves with basic skills required to write API guides.
Auto-generation tools
Auto-generation tools are used with source code files to generate the API guides. Auto-generation tools are helpful in freezing the contents (from the source code files), written by the developers and SMEs, based on the template designed by you. These tools must be customized according to the needs and requirements of the users.
There are a few limitations with these tools, such as:
- No direct contribution from technical writers
- Language inconsistency
- They do not provide great look and feel options
opportunites And challanges
As discussed previously, the API documentation has increased considerably due to rapid growth in companies engaged in software product development. This provides both opportunities and challenges to all the technical writers such as:
- Technical writers will be required to brush up on the skills required to write the API guides
- Technical writers with programming skills will be in demand
- Developers with good writing skills may switch to this field
- Technical writers with domain experience will be in demand
Summary API writing is not a very new field for Indian TWs but we don’t have a large database of API writers. The demand for API writers is increasing due to rapid growth in software product development companies in India. We must be ready to grab this opportunity. To master the art of API writing:
- Learn the basics of at least one programming language
- Learn tools like Doxygen, JavaDoc, Help2Man, Mif2man, Text2man
- Understand the basic programming concepts
- Familiarize yourself with the Unix operating system and the man pages (optional)
Once you are comfortable with API guides, you can also contribute in the programmer’s manuals.
Finally, good news for all budding API writers: salaries are often on par with developers and may be even higher.
Rajeev Jain
Lead Technical Writerrajeevjain@vsnl.com
rajeevjain72@gmail.com
Mobile: 091-93141311170
(The author has over twelve years of IT experience. He has worked as programmer and system analyst with organizations like W.H.O. and DBS Bank (Singapore). He has written books titled Y2K and India, Informatics Practices, and others. He has organized seminars and workshops on topics such as “Software Engineering”, “Visual Basic”, “C”, “FoxPro”, “Y2K Scenario”, and many more.)
- Learn the basics of at least one programming language
- Learn tools like Doxygen, JavaDoc, Help2Man, Mif2man, Text2man
- Understand the basic programming concepts
- Familiarize yourself with the Unix operating system and the man pages (optional)
Once you are comfortable with API guides, you can also contribute in the programmer’s manuals.
Finally, good news for all budding API writers: salaries are often on par with developers and may be even higher.
Rajeev Jain
Lead Technical Writerrajeevjain@vsnl.com
rajeevjain72@gmail.com
Mobile: 091-93141311170
(The author has over twelve years of IT experience. He has worked as programmer and system analyst with organizations like W.H.O. and DBS Bank (Singapore). He has written books titled Y2K and India, Informatics Practices, and others. He has organized seminars and workshops on topics such as “Software Engineering”, “Visual Basic”, “C”, “FoxPro”, “Y2K Scenario”, and many more.)
posted by Rajeev Jain @ 3:00 AM
4 comments
4 Comments:
Where are you seeing the job ads that back up your trend?
From what I've seen the job market has not improved, particularly at the more skilled end of the market.
No one should even think about becoming a technical writer. It is not a career. It is not a profession. These days its a job followed by a long period of unemployment. Each job paying less than the one before. What a trendline.
Much obliged for the information! Thanks!
In this era of web 2.0, we easily get nice & updated information for research purposes... I'd definitely appreciate the work of the said blog owner... Thanks!
................................
writing a term paper-Term Paper Samples
My name is Nitika and I am a Technical Writer by choice. I have been working since 3.5 years in this field and I am very happy……..
If I go back from where I started, I had a very interesting career path.
I started my career from the BPO sector, and then started working in a NGO as a content writer, while working in NGO my sister suggested me to search about Technical Writing field. After doing a lot of research I was convinced about this field and did a course in Technical Writing from Bangalore.
Soon after completing my course I got a job in a finance sector in Gurgaon as a Technical Writer and came across many new opportunities. Suddenly I got a big twist in my and that was “MY Marriage”. I shifted to Bangalore and currently working in a Telecom Company.
This was a small snapshot of my interesting career path.
I am satisfied with the work I am doing and always try to look for the next new development in this field.
But fine one day someone asked me a very simple question, which was, “What is the career growth in Technical Writing?” I explained him the profile but somehow, I was not very confident with the answer I gave. And since then, I am searching for the correct answer. Someone suggested that I should go for further studies like:
• Doing a course in Quality Management
• Doing a Master’s degree in Technical Writing
• Doing a course in Technical Communication and etc.
My search is still on but I am not able to find my answers…
Now, I really want to do some further studies in my field and want to move ahead, but I am not getting the right path and I don’t know, “Which direction to go?”
I really need suggestions from the people who have explored all the different opportunities related to Technical Writing and have achieved success.
Post a Comment
<< Home