This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- CircuitVerse
- Technical writer:
- Pragati
- Project name:
- User Documentation and Guides
- Project length:
- Standard length (3 months)
Project description
After doing an in depth analysis of the audience and current available user documentation, I propose the below documentation tasks:
1) Add video tutorials to demonstrate the popular workflows and improve onboarding experience. Videos will outline a single concept. Videos will give a direction while performing that action on the screen.
A sample video tutorial link for using the Combinational Analysis Tool can be found here. https://www.youtube.com/watch?v=7FkeqBYcd1w Note 1: While this video exemplifies existing content, it is meant to show the style of how annotations can be used to create a consistent video style. Note 2: When I commence working for CircuitVerse, I will purchase a license for the software and the final product will not include a watermark.
Suggested topics for the video tutorial workflows: --Getting Started with CircuitVerse: Watch this video tutorial for a quick tour of the CircuitVerse --Using Combinational Analysis Tool: Watch this video tutorial to learn how to generate circuits using truth table data. --Exporting High Resolution Images: Watch this video tutorial to learn how to export high resolution images of your circuits in multiple formats --Using Subcircuits for Structured Design: Watch this video tutorial to learn how to create sub circuits for simplifying the structure of complex circuits --Using Hex-Bin-Dec Convertor Tool: Watch this video tutorial to learn how to use the Hex-Bin-Dec Convertor tool for circuit design and implementation. --Visualizing circuit timing diagrams for a given circuit: Watch this video tutorial to learn how users can visualize circuit timing diagrams for a given circuit.
Some of the video tutorials can be interlinked across web pages and user documentation.
2) Create a tutorial landing page to give a brief overview of the CircuitVerse platform as well as provide a graphical view of the various workflows. Users will access a tutorial landing page on Circuitverse GitHub site which will provide a brief outline of the various tutorials that are offered for different content workflows. This gives the user the ability to view and choose different tutorials for their needs. Below is a rough sample of the page structure of the tutorial landing page.
3) Create step-by-step tutorials to educate users on how they can use the tool to learn and analyse the behavior of basic and complex circuits–teach the tool by playing with the tool. Referring to the CircuitVerse featured projects, I propose to add at least 5 tutorials for beginner and intermediate level users for improving the onboarding experience. Illustrating a complete workflow, each tutorial will give an introduction to the tutorial, followed by a design process, components list, step-by-step instructions and practice exercises. For complex workflows, videos will cover an individual part of an overall concept.
Visit this link to view a sample tutorial: Build a Seven Segment Decoder: https://pragatijain.github.io/circuitverse/index.html
Some of the topics include: --Build a rolling LED display --Explore how a ripple carry adder works --Part 1A: Analyze a 4-bit magnitude comparator --Part 1B: Building hexadecimal calculator --Analyze a finite state machine (FSM) implementation
4) Revise the structure of the sidebar navigation for improved consistency, readability and cohesiveness.
Project Tools 1) Camtasia for video tutorials. I have used a trial version for making the sample video. When I commence working for CircuitVerse, I will purchase a license for the software and the final product will not include a watermark. 2) Google docs for writing my guides which I will be later updating in GitHub to host in the CircuitVerse repository. 3) Wiki markup and HTML to manage my content in GitHub.
Timeline Before August 16 Make contributions to the organization on GitHub.
Community bonding (August 17 - September 13) Set up a communication channel and time (due to time difference). Refine my goals and set expectations on both sides. Learn more about the community and product. Discuss and finalize the proposed documentation structure with the mentors and other members of the organization.
Documentation period This project will follow the standard length project guidelines (11 weeks total, from 9/14/2020 to 11/30/2020). I will spend around 20 hours a week completing the goals that are outlined below. In addition to these goals, I will take part in mentor meetings and communication during this time, as needed. I will work with the mentors to determine the best time for this. Note: This timeline is flexible and recognizes the fact that organizational needs can change. The large timeframes allow for flexibility and the ability to switch focus, as needed.
Week 1: Review identified milestones and refine them Fork CircuitVerse repository and download it to my machine Discuss with mentors the style for videos, as well as develop a video opening screen template, any filler music for the title and ending screens, and additional information that should be included. Review video tutorial topics and get it approved Identify tutorial topics and get it approved. Review sidebar navigation structure and get it approved
Week 2: Build tutorial template and get it approved by the mentor Create tutorial landing page for hosting the tutorials
Week 3, 4, 5: Add video tutorials to demonstrate different simulator workflows
Week 6, 7, 8, 9: Create tutorials for different simple and complex circuits
Week 10: Restructure the sidebar navigation for consistency to improve the user onboarding experience
Week 11: Proofread my work for typos and errors.
Relevant CircuitVerse Work Samples
*Visit this link to view a sample tutorial: Build a Seven Segment Decoder. : https://pragatijain.github.io/circuitverse/index.html
*A sample video tutorial link for using the Combinational Analysis Tool can be found here. https://www.youtube.com/watch?v=7FkeqBYcd1w Note 1: While this video exemplifies existing content, it is meant to show the style of how annotations can be used to create a consistent video style. Note 2: When I commence working for GDevelop, I will purchase a license for the software and the final product will not include a watermark.
*CircuitVerse Tutorial Landing Page https://docs.google.com/document/d/1sBKS2cq76zRHDGgA2Lbf7isSisRK_ELLSPsg-7atCAI/edit#
*View complete proposal as a google doc: https://docs.google.com/document/d/1vzYyDnX6mFXXByrcwVsrxCgpIWKpcj8U8DSa3gVB7RA/edit#
Sample Tutorial Template: 7 Segment Decoder 7 Segment Decoder
Overview:
This tutorial shares with you different steps for creating a 7 segment decoder using CircuitVerse. A decoder is a combinational circuit which converts a binary number to the corresponding decimal number. It takes in four bits of input and has seven outputs.
Design Procedure
For generating the 7 segment display circuit in CircuitVerse, we will follow the below steps: Use the Combinational Analysis tool available within the CircuitVerse simulator to formulate the truth table. Using this truth table, we will then generate the circuit within the simulator. This circuit will drive output to a seven segment LED display. Connect the respective labels of the combinational circuit to the respective outputs of the seven segment LED display to see our circuit in action. A seven-segment display is an electronic display device for displaying decimal numerals from 0 to 9.Refer Analyse the circuit behavior using the truth table data. Truth Table Table 1 below lists different outputs for different combinations of input for a 7 segment decoder.
CircuitVerse Elements List
Table 2 lists the different components required for implementing the circuit.
Formulate the Truth Table
Follow the below steps to formulate the truth table within the CircuitVerse simulator:
Complete the circuit
Refer Figure 10 to connect the respective input wires for corresponding labels of the combinational circuit to the respective outputs of the seven segment display to complete the circuit. This video demonstrates a 7 segment decoder simulated circuit built within the CircuitVerse simulator. Video Link: https://www.youtube.com/embed/tGTy4P-RxP0
Analyze the Circuit
Toggle different input values (S3, S2, S1, S0) and validate the truth table (refer Table 1) to verify the implemented seven segment decoder circuit.
A seven segment display component has 8 LED segments inside it and have one end of their pins pulled out of the module as shown in Figure 8. To make an LED of a particular segment glow, relevant segments (labeled as a, b, c, d, e, f, g in Figure 10) must be powered up to represent the numbers from 0 to 9. For instance, for displaying number 1, LEDs b and c must be powered up.
If the LED fails to display the right decimal number, refer to Table 3 and Figure 10 and troubleshoot your wiring connections. Table 3 lists the 7 segment display pin configuration.