README: The Developer's forgotten love letter
Room A | Thu 22 Jan 11:40 a.m.–12:25 p.m.
Presented by
-
Swapnil Ogale has consulted at, and worked with multiple organisations for the last 20 years, setting up documentation teams, process, workflows and tool-chains. This includes strategising content needs, setting up information architecture, and facilitating user research for documentation sites. He currently works at Amazon Web Services (AWS) Australia working with internal teams and external customers to create robust technical documentation across tools and solutions.
Swapnil Ogale has consulted at, and worked with multiple organisations for the last 20 years, setting up documentation teams, process, workflows and tool-chains. This includes strategising content needs, setting up information architecture, and facilitating user research for documentation sites. He currently works at Amazon Web Services (AWS) Australia working with internal teams and external customers to create robust technical documentation across tools and solutions.
Abstract
READMEs are deceptively simple files. Often written as text files, they are often lightweight and regularly overlooked, but, make no mistake, they are their worth in gold. Developer-driven open sourced projects, in fact, millions on them are built on a premise that some other developer will most likely stumble upon it, clone it, and use it to solve their own tech challenges. The first stumbling block usually arrives in the form of supporting documentation (or lack, thereof).
How can developers ensure that they use good documentation practices to create a simple and straight-forward file (the README) that will be the make-or-break moment for their project's usefulness?
In this short talk, a technical writer who has worked with a number of software teams, and helped draft and review good README files, will dust off the cobwebs off the lost art of good README documentation, and provide some tips on how to create docs that work for multiple audiences.
READMEs are deceptively simple files. Often written as text files, they are often lightweight and regularly overlooked, but, make no mistake, they are their worth in gold. Developer-driven open sourced projects, in fact, millions on them are built on a premise that some other developer will most likely stumble upon it, clone it, and use it to solve their own tech challenges. The first stumbling block usually arrives in the form of supporting documentation (or lack, thereof).
How can developers ensure that they use good documentation practices to create a simple and straight-forward file (the README) that will be the make-or-break moment for their project's usefulness?
In this short talk, a technical writer who has worked with a number of software teams, and helped draft and review good README files, will dust off the cobwebs off the lost art of good README documentation, and provide some tips on how to create docs that work for multiple audiences.