Writing Your Header
Put the project name at the top using a 14-pt or 16-pt sans serif font. This is the name of your product or the working title of the project itself. Use a sans serif font in 14-pt or 16-pt so it's easy to read. Left justify it or center justify it, depending on your preferences. Your workplace or instructor may provide you with a template that shows you how to write your title. Always follow the template if one is available.Did You Know? A sans serif font doesn't have end strokes on the letters, so these styles have a more modern look. The most popular sans serif fonts are Arial, Calibri, and Verdana.
Write the date below the project name in a 12-pt sans serif font. Go to the next line and reduce your font size to 12-pt. Use the same sans serif font that you used to write your project name. Then, type in the date using the month, day, and year. If your template is different, format your date according to the template. It’s important to include dates so you can tell which tech spec is the most recent one.
Type “Author” and the author’s name under the date. Go to the next line and write “Author,” followed by a colon. Then, put your name since you are the one writing the tech spec. Always put just your name, even if you discussed the contents of your tech spec with a team. A tech spec always needs to have one author, even if you’re working with a team. The author is the person who actually types up the spec.
Place “Team” and the names of the team members last. On the next line, type “Team,” followed by a colon. Then, write out the names of each team member who is working on the project or product. In addition to giving your team members credit, this helps people understand who they can go to if they have questions about the tech spec. If you worked alone on this project, skip this step.
Drafting a Tech Spec
Provide an overview or brief summary of the project or product. Start your tech spec with a summary of what you’re doing. Type “Overview” or “Brief Summary” as your header. Explain the problem, then summarize what the project or product is and what it will do. Next, explain what your approach for accomplishing it will be and include product specs if it's equipment. Link to any marketing or engineering documents that are important to the project. Finally, provide a rough time estimate for how long it’ll take to finish the project or product. You might write, “The current system for planning transit trips across the county leaves riders stranded and lowers ridership on certain routes. Two of the bus systems allow riders to plan their trip online, but the third uses paper maps and phone contact. This solution is lowering ridership and causing under funding, see Spring 2019 survey results. We want to move all 3 transit lines onto 1 planning system that users can access online. This will allow them to plan their trips more easily and see when the buses will be at each stop. Additionally, riders can report issues immediately using a 'contact us' function.”
Include a goals section if they’re not in the overview or brief summary. Type “Goals” as a header, then briefly outline what you plan to accomplish with your project or product. Write a lead-in statement, then list your goals in a numbered or bulleted list. If you outline your goals in the overview section, you don’t typically need this section. However, you may be required to include this section if your workplace requires it. Write something like, “The new system will include: 1) A route planning tool; 2) A bus locator function; 3) A way for riders to report problems.”
Write the product requirements in a separate section. Next, type “Product Requirements” as a header, followed by the things your product needs to do to solve your problem. Use a bullet list and don't worry about a lead-in sentence. For instance, “1) Route planner ensures riders aren’t stranded and buses aren’t underutilized; 2) Contact box allows transit planners to directly respond to rider issues.”
Explain things that are out of the scope of your project. Title this section “Out of Scope” or “Non-Goals.” Don't write a lead-in or paragraphs. Instead, create a bullet list of the things you aren’t going to do to solve your problem. This includes work that you won’t do, solutions you don’t think will work, and attributes your product or project won’t have. Be thorough so that the client and your team won’t have any misunderstandings. You might write, “1) This system won’t add new bus routes; 2) We will not install computers at bus stops or on buses, so riders will need to use their own devices; 3) Transit planners will not guarantee immediate solutions to rider problems; and 4) This service will not include door-to-door pickups.”Variation: Sometimes this section is placed near the end of the tech spec before the timeline. Use your preferred placement or do what's most common in your workplace.
Include an “Open Questions” section if you have unresolved issues. Your tech spec is a quick outline of the product or project so your client understands what they’re getting and your team is working on the same goals. Don’t worry about including every detail or answering your “to be determined” questions. Instead, type the header “Open Questions” and present a bullet list of the things you’ll decide later. Write, “1) How will we manage system updates? 2) Will we change the route maps if we find a problem? 3) Can the system serve a multilingual ridership without translation errors? 4) How will we best serve riders who aren’t tech savvy?”
Present your plan in the "Approach" section. Title this section either “Plan” or “Approach.” Describe how you will solve the problem or the different approaches you are considering if a final decision hasn’t been made. Explain your research and each technology or process that you will use. If possible, include illustrations, charts, and diagrams so that it’s easier for your readers to understand your plan. Finally, discuss how you will test your plan and what you will do if there are issues. If you describe different approaches or technologies, create a subsection for each one so that your plan is easy to follow. Write something like, “We will work with the transit planning team to design software that allows riders to input their destinations into an app that will generate a route for them. Riders can then alter the route if they desire. The system will send text updates to riders to help them find their routes. We are going to have the riders on a stakeholder committee test the software before we release it to the public. If the plan has errors, we will make site updates during hours when the buses are offline. Additionally, we will have an extra shuttle bus available to pick up passengers that are stranded because of the system.”Variation: You might include a “Components” section at the top to summarize what your plan or approach will entail. However, this is usually optional, unless your company or instructor requires it.
Include the other options you considered but ruled out. Put this section as a substep in your plan or approach or place it at the end of your spec before your timeline. Type the header “Other Options Considered,” then describe the alternatives you considered before you chose your current plan. Explain why your ruled out each option. You might write, “We considered color-coded maps because it’s a cheaper option, but riders didn’t respond well to the existing maps and the test group got confused.”
Describe your methods and metrics for evaluating the product or project. Include this information in one section or multiple sections. Title it something like “Measuring Impact” or “Monitoring” and “Metrics.” In one or more paragraphs, explain how you will make sure your product or project is working correctly and accomplishing your goals. Additionally, describe how you will check for bugs or problems. Include the specific analytical processes or technologies you’ll use. Say something like, “We will compare projected route times to actual route times to make sure buses are on schedule. Additionally, we will conduct a rider survey to evaluate their satisfaction and identify problems with the system.”
Identify how you will provide security and privacy. Type the header “Security and Privacy,” then explain how you will protect users from cyber attacks. Briefly describe the risks and how you will secure your system so privacy is protected. Write a couple of paragraphs to explain your methods. There are always risks or concerns, so don’t put “there are no risks” in this section. You might write, “Users will enter their location and their home addresses. Additionally, they’ll have the option to create a profile and save trips. To protect this data, we’ll include encryption and a firewall.”
Finish with a timeline and list of milestones. A timeline helps keep your project on track and tells both your client and your team what needs to be done. Title this section “Timeline,” then breakdown the tasks according to who is doing them. Include a bullet list for each team or team member, depending on your preferences. For instance, your task breakdown might list “Engineering Team,” “Planning Team,” “Marketing,” and “Quality Assurance.” Your bullet list for the engineering team might include tasks like, “1) Write website upgrade; 2) Write trip planning app; 3) Write contact system.”
Finalizing Your Tech Spec
Single-space your document and skip 1 line between sections. Use single spacing so that your tech spec is shorter and easier to handle. When you want to change paragraphs or sections, just skip 1 line. This helps the reader keep up without adding unnecessary pages. Your workplace or instructor may give you different formatting instructions. If so, follow these instructions.
Use a first-person point-of-view throughout your tech spec. Since you're discussing work that you and your team will accomplish, always use the first-person pronouns "I," "me," "we," and "us." When you're referring to a particular team or person, use their name so it's clear who you're talking about. This keeps the tech spec direct and to the point because the reader knows how will be completing each action. For instance, say, "We will update the specifications as needed" rather than "The specifications will be updated as needed." Similarly, write "The engineering team will write a website" or "Amy will draft a marketing plan."
Write clear and concise text that's easy to follow. Don't elaborate on your ideas in a tech spec because it wastes both your time and your reader's time. Use as few words as you can to express your ideas and organize your thoughts so they're easy to follow. Go through your report and eliminate unnecessary wording and repetitive sentences so your report is more direct. For instance, you could revise "We will write a website that allows riders to plan their desired trip and keep track of the bus" to "This website allows trip planning and bus tracking."
Get a partner to review your tech spec and provide feedback. Share your tech spec with a team member or classmate who will understand it. Ask them to mark errors they see and give you feedback on where you can make improvements. Don’t show your tech spec to someone who doesn’t understand your field. They’ll likely get confused and may recommend changes that aren’t necessary.
Revise your tech spec if changes are needed. Based on the feedback you received, go back through your tech spec and make revisions if you feel they’re necessary. Focus on making the tech spec understandable to clients and your team. However, don’t worry that it’s not perfect. You’ll likely need to update your tech spec as your project or product progresses. This is a temporary document, so don’t let it prevent you from doing your actual work.
Proofread your tech spec before you distribute it. Read through your tech spec at least twice to check for errors. If you can, read it aloud to help you catch your mistakes. Focus on things like typos or words that might change the meaning of your document. For example, look for errors like “the current system is efficient” rather than “the current system is inefficient.”
Comments
0 comment