Writing Open Source

An Open Source Documentation Conference

What's This?

Hey there – looking for the documentation conference founded by Emma Jane Hogbin, Belinda Lopez, and Addison Berry? Well, you’re in the right place, but Writing Open Source is no longer available as it was. Don’t worry though, we can still point you to other open source documentation conferences and style guide resources on this page – you can give them a quick look before you go, if you’d like.

Alternative Websites

Open Help

Open Help holds an annual conference focused on documentation, support, and education issues in and around open source and open communities. In addition to the conference, Open Help hosts documentation sprints and facilitates the exchange of ideas, where teams can share thoughts and socialize. You can also get in touch with them on Twitter, and catch them on YouTube.

Write The Docs

Write The Docs is – in their own words – “a series of conferences and local meetups focused on all things related to software documentation”, focused “on documentation systems, tech writing theory, and information delivery”. Check out their events in North America, Latin America, and Europe; go through the documentation style guide; and connect with Write The Docs on Slack, Twitter, and YouTube.

Information Energy

Information Energy is an annual conference of content developers and information professionals, where discussions focused on “trends in managing, using, editing, finding, sharing knowledge and information” take place and ideas are exchanged. Check out the website for more information about the annual meetings, speakers, topics, among other things; you can also get in touch with Information Energy via Twitter.

18F Open Source Style Guide

18F is a team of experts who help government agencies “build, buy, and share efficient and easy-to-use digital services”, and the 18F Style Guide is their take on helping people document code repositories to improve readability, usability, and make them easy to understand. Afterward, you check out their main website, and you can also find 18F on Twitter and on GitHub.

Google Style Guides

Check out Google’s own style guides – while primarily for Google-originated open-source projects, they encourage everyone to share and build on these existing conventions for the greater benefit of all. You can find the main Google Developer site here, and read the blog here; you can also find them on social via Facebook, Twitter, Medium, Google+, and YouTube.


Docs or it didn’t happen

Does documentation really matter? Mikey Ariel talks about the Whys and the Hows of good documentation.

Git and GitHub for open source documentation

Opensource.com’s Mikey Ariel dishes on using Git and GitHub for project documentation, particularly on scalability and best practices.

How We Tamed Swift Syntax: the Open Source Style Guide

Netguru’s Radosław Szeja writes about the issues they had to deal with starting out, and the road to getting the style guide done and what it meant for their development processes.

18F’s style guide for open source project documentation

18F’s Melody Kramer talks about their style guide, why it matters, and where to go from this point onward.

In Search of a Living Design System

Jina Bolton talks about her road to discovering living style guides, why they matter, and the future going forward.

The Rise of Technical Writing

Let me Google that for you” – is one of the go-to teaching tools most frustrated IT experts – both professional and de facto in familia – use to both instruct and drive home a point: when you want to learn something, there’s documentation with instructions on how to do just that available somewhere and it’s quite easy to find, please stop bothering me.

Now, could you imagine being in the same sort of situation without said documentation or references to refer your beloved luddites to when they want to figure out how something should work? When they come to you for help? Well, what might have been a relatively minor irritation may well become a nightmarish struggle to explain how things work in general.

With the near-exponential advances in technology and uncountable new innovations and inventions of the past two centuries, to imagine a world without documentation is just plain headache-inducing, and a few generations dying out away from losing any and all progress we’ve managed to accomplish.

On one hand, having a situation like the above happen borders on the absurd, but it also serves to underline the importance of writing – in this specific case, technical writing – to progress and… well, to keep the world going as it is, to put it in stupidly simple terms. (As an aside and interestingly enough, writing is considered a technology in and of itself – arguably the most important one we’ve developed, all things considered). [1]

From this point on, it’s easier to see where things stand and where things are going toward, but it’s also interesting to have in mind how technical writing got started and slowly, surely became fundamental to how the world works today.

Early Developments in Technical Writing

Many consider the works of Aristotle as an example of the earliest forms of technical writing. Geoffrey Chaucer’s A Treatise on the Astrolabe – an instruction manual on the scientific instrument – as being the first technical document published in [Middle] English. [2]

Beginning around the 14th Century, two key events played significant roles in highlighting the importance and necessity of technical writing: the invention of the printing press, and the Renaissance. As the number of discoveries, innovations, and inventions began to rise, so did the need to record and document these new developments for the purposes of preservation of progress and dissemination of knowledge.

Come the Age of Enlightenment during the 18th Century, technical writing – though still not considered as an occupation in and of itself, nor texts produced considered under that particular nomenclature – had essentially been established as a fundamental part of sociocultural progress and development. [3]

Technical Writing in the Modern Age

During the industrial revolution, as more complex machinery was being invented and put to use, the need to instruct and educate people continued to grow, with more. [4] World War I and II led to advances in medicine, military hardware, and computer and aerospace technologies, and it was during the time of the second world war that technical writing as a profession and a job title became officially recognized. [5]

Invention is the Mother of Necessity

Post-war, progress continued: standards of living rose, more consumer goods started flowing in, and infrastructure growth and improvement all increased the need to chronicle and document everything involved in using, maintaining, and improving these developments. During this period of time, businesses and educational institutions began to use computers more.

In 1949, Joseph D. Chapline wrote an instruction manual – the first computer user manual ever – for the BINAC computer, widely considered to be the first piece of “established technical writing” published (he also documented the UNIVAC computer in 1952). [6][7] Chapline also taught courses in technical communication at the Moore School of Engineering of the University of Pennsylvania. Later on in 1957, the Society for Technical Communication was formed, “dedicated to the advancement of the theory and practice of technical communication”. [8][9]

As technologies advanced and materials began to get cheaper, the computer continued to grow in prominence, gradually entering the consumer space, in addition to more and more businesses making good use of newer, more affordable devices. This rapid growth further boosted the need for technical writers to document and explain the new and how to employ these computers in day-to-day use and operations.

Regarding some more significant milestones for technical writing in the modern era, ProEdit writes:

  • 1975: The U.S. Government required all product warranties to be stated clearly and unambiguously.
  • 1976: The Modern Language Association (MLA) approved a panel on technical writing at its annual conference.
  • 1980: In an immigration case involving the question of the occupation classification of a technical publications writer, the U.S. Department of Justice ruled that technical writing is a profession.
  • 1987: Early desktop publishing and page layout software began appearing on writers’ desktops, including products like Ventura Publisher, Interleaf, FrameMaker, and Aldus PageMaker.
  • 1991: ISO 9000 certification requirements created new job opportunities for technical writers.
  • 1999: Writers began using XML, an “eXtensible Markup Language” that is evolving from HTML.
  • 2002: The Sarbanes-Oxley Act of 2002 creates new opportunities for technical writers documenting policies, procedures, and internal controls.

(Check out ProEdit’s full article on the History of Technical Writing by clicking here).

The Future of Technical Writing

Today, computers and digital communication are central to our lives – both at home and at work. Institutions – educational, governmental, political, and quite honestly, every kind – rely increasingly on both hardware and software solutions that become increasingly complex as much as the work to refine interfaces and processes are a constant focus for many of those who develop these.

Continued progress and technological development simply requires documentation, and the constantly increasing need for more technical writers (as well as the continued growth in the craft of good technical writing) reflects this need.

As the world – and the lives of everyone living in it – becomes more complex and more interesting (as a net result, anyway), the need for people to easily understand and learn to use everything – from the things we use every day to the technologies that push businesses and nations forward – grows as well, and that translates into more and more demand for technical writers, those who chronicle everything that matters and who [at the very least] have the ability to ELI5.

About the Author: Andre Salvatierra is a freelance writer who loves culture, technology, well-designed things, and great experiences. You can find him on Medium and Twitter.

[1]: https://en.wikipedia.org/wiki/Writing
[2]: https://en.wikipedia.org/wiki/A_Treatise_on_the_Astrolabe
[3]: https://en.wikipedia.org/wiki/Technical_writing#History
[4]: http://eprints.port.ac.uk/9695/1/trans-kom_05_01_03_Crabbe_Technical_Writing.20120614.pdf
[5]: http://www.msubillings.edu/cotfaculty/fullon/_notes/History%20of%20Technical%20Communication%20%282%29.pdf
[6]: https://en.wikipedia.org/wiki/BINAC
[7]: http://www.proedit.com/history-of-technical-writing/
[8]: http://idratherbewriting.com/2014/11/07/the-evolution-of-technical-writing/
[9]: https://en.wikipedia.org/wiki/Society_for_Technical_Communication

All references accessed May 2016.