Last updated on Nov 27, 2020
Andrew Etter, the Senior Technical Writer at Amazon Web Services, joins us in this episode of Knowledgebase Ninja to share most important aspects of documentation and his experience working with Amazon. Check out all the other episodes of Knowledgebase Ninja here.
Connect with Andrew Etter and Amazon Web Services here:
Andrew’s journey into technical documentation
Andrew’s experience in the software industry is now more than twelve years. His journey started when he was searching for the jobs back then, and after applying multiple times, he finally got called for an interview. However, the interviewers suggested that technical writing is a better fit for him instead of that software-related job. Thus, Andrew decided to give it a shot.
Even though Andrew got into technical writing after being tired of travelling here and there, searching for jobs but now it has been more than seven years, and he still loves his job. He realised that in this field, you could help millions of people.
Documentation process at AWS (Amazon Web Services)
The process includes testing what is working for the team, drafting the entire content and then sending it to the engineering team to view and check if there’s any problem.
The product development team is often contacted to take help when the team is not sure about the usage and to get an insight into it. When the documentation is done, the focus is then on metrics to keep a check if users are getting confused in something.
Etter said that every day the process goes through some changes. The development team, product team and support team work closely and so, these are the major contributors.
The positive side of open-sourcing content
He explained that to him, there is no harm associated with open-sourcing your content as he thinks that the content is already available if it is being uploaded on the website. So, putting the source there would not harm anybody. Andrew suggested that this builds the trust of users as they are asked for contributions, and they can have a direct relationship with you. He gave an example of AWS where if he gets a bug report on his open-source content, then he easily finds how to fix it most of the times. This shifts the entire relationship with readers as together the content is taken to the best state possible. Moreover, it has its inclusivity as anybody in the world can access the open-source without having to purchase the license for such expensive software.
Factors considered in the documentation process
Andrew shares that the first one should consider its users very smart. So, surprises should be minimised for the users as while critically examining; if there is something new, then it should be documented just so users know that if they do this particular thing, the consequence will be this.
Besides, limitations should also be mentioned for the users so that they do not have to deal with a bad experience. This is also another way of minimising surprises. Furthermore, if there is an example, then it should be used to start the document and not just put it at the end.
Unnecessary details should be avoided, and for the ones who want to know more in-depth, links should be attached instead of just adding more and more paragraphs. For Etter, this is a factor that explains that they want to help people.
Did quality documentation decrease workload?
It has been opposed to him. The organisation he is working in has grown by twice or thrice since the time he joined. Although, he thinks that there would have been a decrease in workload if the team size remained.
Who has inspired Andrew in documentation?
He learnt the most about documentation by a developer at his previous company. He shares that some tools in his previous company were kind of suboptimal and so, after lots of research, Etter gathered his assessment of tools to present. Still, before that, he visited this developer, Mike. The developer recommended using lightweight markups instead, and he focused on the capabilities of everyone in the company, and for him, contributions from around the world were necessary. This mindset is what Etter embraced that you should always go for open-source whenever possible.
Favourite documentation resource
Etter’s preference was Tom Johnson’s blog, as he thinks that he is an interesting person with excellent skills. He recommended visiting the blog once because he found it perfect.
What documentation related advice would Andrew give to his 20-year-old self?
He would tell himself about ‘inclusivity’. When your content is going to be accessible to the whole world, you need to make it user friendly by only using tools that are readily available and free for them. Also, the content should be designed in a way that has an option for contributions by viewers. Make sure that locals are not confused by the way content is written and appropriate language should be chosen.