Hello, I’m Kelly, a former team captain, design lead, documentation lead, alum and current mentor for Team 1778 Chill Out. I got inspired last night to write down a full description of the process I’ve just naturally learned by writing the team Safety Manual and doing work on the team’s various Engineering Handbooks (all WIPs, probably will be posted to ChiefDelphi when/if they get finished by the team). It ended up being so long that I thought it wouldn’t be so bad to post it on ChiefDelphi.
There are two major components to putting together handbooks/manuals for the team. The first is defining a technical documentation standard for every handbook. This includes the title page, the table of contents, how each chapter is titled and linked to, and the way information is put together in each chapter depending on how you want to present the content. For example, an initial explanation and then bullet points, or maybe separate bullet points with an explanation under each one, etc. Style formatting is included in this, so basically it’s just how each section title is organized and formatted, i.e., the title, heading 1, heading 2, heading 3, normal text. The first time you create a team handbook, this standard is put together over time as you build the content and go back and change the layout (I will go over this later). Different types of handbooks may require different common ways of presenting the information (engineering handbook will be different than the safety manual), but the style formatting should be the same. If you switch it up in a new handbook, make sure to change all other manuals to match.
The second major component is the external resources: steal from the best, innovate the rest. The first thing I do when I want to create a new handbook or document is look for and open every related resource imaginable. For the safety manual this included all prior team safety manuals, stuff we’d put together for awards and such. There were quite a few variations of the safety program, including different ways of wording (and different typos that I had to go through). I also pulled up safety resources from 358 iirc and other ones from across the community. Later, if I needed specific information about a specific thing, I looked it up or asked. For stuff like my electrical handbook, which includes standards and best practices and best places to buy things, I consistently had open tabs like Andymark and Rev and even some related ChiefDelphi discussions (which I keep finding and adding) so I could include hyperlinks to various resources.
The purpose of finding the resources and doing research first was to figure out the various types of content there were. Specifically, this leads into creating a draft of the layout (what will hopefully be the table of contents, how the content is laid out). EXPECT THIS TO DRASTICALLY CHANGE WHILE WRITING; however, the more research you do on the different kinds of content first, the better idea you’ll have of the ideal layout for presenting the content in a practical way. The layout of course can’t just be random; the key to technical writing that you’ll learn in every technical writing class is to cater to the audience. What is your audience expecting to get out of this resource, how are you expecting them to use it? Print it and put it in the corner of the shop for people to refer to or keep it digital so someone needs to pull it up on the computer every time they want to look at it? What’s the easiest way for them to find what specifically they’re looking for without hassle, specifically for a safety manual intended for quick reference at a competition? You’ll kind of intuitively (this will get more accurate over time) know a good enough layout for the content that you’re aware of, but as you discover more content that you have to fit in, the categories you previously created to fit the content you knew before might not be good enough for the categorization of all the new content, so you’ll have to rename categories to fit a broader or narrower field of content or create new categories and reorganize existing content to fit into those because you had more content of a specific category than you once had (that was a long sentence I know). And of course you’ll have to make all those decisions in the context of making it perfect to use as a resource for your audience.
As you write the content of the handbook or manual, you’ll constantly pull together information from different resources. I wasn’t afraid to copy and paste because some people already worded things perfectly (make sure to cite sources, give due credit!), but make sure to reformat it according to your standard and layout. You’ll end up writing your own stuff no matter what as a part of making the layout yourself; for example, as initial explanations, as paragraphs piecing things together, and as advice from your own experience. You might also rephrase content you’ve found from external resources so it fits better with your layout. Usually I go through most of it, I get stuck on some stuff or am just missing some knowledge that I know is out there so I create an outline of what exactly is supposed to go there, once I (or someone else) find the knowledge.
Once you’re done with the rough draft, have a few different people who also know the content or can at least read, read through it. The kind of mistakes you can make while reformatting text is surprising but sometimes things just won’t make any sense no matter how confident of a writer you are. Most importantly, get feedback from your targeted audience on how easy to use practically it would be. Go through the editing process with comments and suggestions, and then it’s ‘finished’. Be very prepared to go back and change some formatting if the documentation standard changes after doing more handbooks/manuals or when information or opinions on best practices change, or if you suddenly get new information that you didn’t have before, then have that section reviewed again.
I was able to jump into doing technical documentation more easily because of my skills in writing and experience with having foresight about how to give clarity about a topic to the person with least context. Pretty much anyone can jump in and, as long as they give attention to creating a formatting standard, learn and improve by themselves through the process. I know how useful it is to examine resources made by people who have already been through the process of doing something in order to expedite one’s own knowledge and understanding of the topic, so I figured I’d put this up to be one of those resources. Thanks for making it through this if you did, and good luck with your own documentation.
Here’s the link to the safety manual: 1778 Chill Out Robotics Safety Manual - Google Docs
It’s also found on our website, https://chillout1778.org