User Documentation: Final Report (GSoD 2020 - Pragati)

Final Project Report


My project focused on creating videos and documentation for CircuitVerse (CV) User Documentation. This documentation encompassed all aspects of the CircuitVerse simulator, aiding educators (the primary audience) in teaching digital logic design through computer simulations with ease. I was tasked with creating one explainer and multiple learning videos for different features and functionalities of the platform, aiding user technical literacy, and updating and creating new user documentation.

Deviations From The Original Proposal

My original proposal focused on CircuitVerse content workflows. I proposed to create videos, user instructions and tutorials that would demonstrate users (students, hobbyists, educators) could use the platform effectively for building simulations.

After the Community Bonding period, the team and I decided that I would focus on developing videos and text that drive adoption of the platform, especially for the primary audience (educators). While the documentation addressed the entire CircuitVerse platform, the videos played a key part in improving the on boarding experience and in demonstrating the key workflows of the platform. Since it is important that current content is audited, validated and updated for driving user adoption, the team decided to prioritize this task above creating tutorials. Finally, information (old and new) was organized, structured, and labeled in an effective, coherent and sustainable way. Chapters and subchapters were created for making the content searchable.

Project Deliverables

1.Explainer Video: This task involved creating a video that showcased the CircuitVerse platform to a new user. Besides sharing the key inspiration behind the CircuitVerse platform, it shares the key features and workflows that allows users to build and simulate circuits on the go. I had purchased the TechSmith Camtasia 2020 for creating and editing the videos.

Using the available assets in Camtasia, I created different art affects for including in the videos. Once these art affects were created, they were rescued across different videos for brand building.

Link to video: Introduction to CircuitVerse Platform Status of deliverable: Complete

2.Instructional Videos: This task involved creating 7 different videos that demonstrated the foundational knowledge the users need to better understand the platform. These videos can be reused by the educators (primary audience) during planning their classroom assignments.

Status of deliverable: Complete

Table 1: Different videos created to explain the CV simulator

Sr. NoNameDescriptionLink
1Make Your First Circuit Simulation With CircuitVerseThis video demonstrates how you can build your first live circuit using CircuitVerse simulator.
2Using Subcircuits For Complex Design SimulationsThis video demonstrates how subcircuits can be reused for constructing a hierarchical design.
3Editing Properties For Complex Design SimulationsThis video highlights different properties of different circuit elements that can be edited for building a complex design.
4Insert CircuitVerse Live Circuits in Google SlidesThis video demonstrates how a CircuitVerse add-on can be used to embed live circuits in Google Slides.
5Customize Your Simulator WorkspaceThis video demonstrates how the CircuitVerse simulator screen can be easily customized while building circuit design.
6Using Combinational Analysis ToolThis video demonstrates how the Combinational Analysis tool can be used for building a seven segment decoder
7Saving Projects Within The CircuitVerse SimulatorThis video demonstrates how the circuits can be saved using the CircuitVerse platform

3.New UI Revamp Documentation: While videos improve the on boarding experience, the user documentation offers detailed explanations of different features and functionalities for users to be more successful while building the simulation.

While preparing for the GSOD proposal, I had extensively audited the existing documentation for documentation gaps and improved areas. For this task, I referenced existing documentation for exploring different specific technical details of different circuit elements. I used the existing referenced live circuits in my documentation also. This process also entailed several meetings and review sessions with subject matter experts (SMEs) to gather input and additional information.

While the documentation was being created, the CV platform was also getting revamped with new features and workflows. The mentors apprised me about the developments as the documentation developed. While most of the documentation is completed, some sections must be updated to reflect the new added features of the CV platform.

As I continue to work on the project, some of the key documentation tasks accomplished include:

  • Updated the document’s style and format
  • Added content for new features and functionalities
  • Developed new figures and tables as visual aids
  • Improved the content hierarchy and flow by adding chapters and subchapters for making the content more searchable

Link to guide:CV User Online Documentation Status of deliverable: Incomplete. While most of the documentation is completed, some sections must be updated to reflect the new added features of the CV platform. This guide will be completed by the end of December. The CV mentors are aware of this.

4.Support Resources: A good user documentation must take the burden off the CV mentors. I studied the queries received across CV Slack channel and CV forums to understand user pain points. I created a FAQ document and included a section that described the best practices for using CircuitVerse.

Link to guide:CV User Online Documentation Status of deliverable: Complete.

5.Contributing Guidelines: This task refers to the different content guidelines that new users must follow while submitting content for ensuring that the submitted content is consistent and adheres to the suggested style guide. This shall also help in maintaining the document as the platform scales up. The documentation has started and will be completed by the end of December.

Link to guide:CV Contributing Guidelines Status of deliverable: Incomplete. This guide will be completed by the end of December. The CV mentors are aware of this.

Technologies Learned

This project allowed me to gain experience using a variety of different technologies and tools. I became more proficient in the following programs:

  • Screen capture software and captioning software: I purchased the license for using TechSmith Camtasia Software for screen recording and editing the video content. This was my first time using this software. I thus challenged myself to learn different tips and tricks for making professional videos and master the application in a short amount of time. Some of my key learnings for making good quality videos include:

    • Add an eye-catching intro
    • Use cursor effects to highlight cursor movements
    • Add transitions for improve flow across different frames
    • Use animations to add some glamor to the content.
    • Use Camtasia in-built library assets for creating CV branding assets

    After creating two videos, we shared those with the CV community on Slack for feedback. While the core content of the video was appreciated, I received critical feedback on the intro part and adding tone with a music score (along with the narration).

  • GitHub: For publishing my content, I must use GitHub to push my content. Since I have limited experience with the tool, I hope to grow more comfortable with these technologies and participate more actively online. I shall use the tool once the final word file has been reviewed.

Lessons Learned

1.Open source documentation: One of the key pain points or blessings of working on open source documentation is that the platform is continuously upgraded with new features and functionalities. So how does one know how to strike a balance? While the CV videos had some UI discrepancies, the user guide content (that is live) must be detailed enough to give users clear instructions on how to accomplish a task. I learnt that videos play a key role in demonstrating a workflow while the text documentation must be detailed and must be updated frequently.

2.Audience analysis is key: Again, I have learnt that audience analysis is key to the success of a documentation project. Do your research and ask enough questions to your SMEs to understand your audience and discover vital facts. Advocate for your user because this is also your chance of understanding, and reason with your team why your suggested documentation plan will not benefit your audience.

3.Documentation plan is important: When working on any team, organizational needs can change over time. I set up deadlines that allowed me and my mentors to assess my progress, identify hurdles and revise documentation scope.

4.Communicating and time management skills for remote collaboration: I had to work remotely with SMEs residing in other parts of the continent to understand and document organizational requirements. While the team was always available to answer my queries, I developed even stronger communication and organizational skills.

Final Thoughts

GSOD has been a rewarding learning opportunity for me. I have learnt a lot. I educated myself on Camtasia and explored different tips and tricks for creating impactful videos. Besides developing a tool proficiency, the key thing is audience analysis. This is very instrumental before you step into your first discussion with your mentors.

This program has allowed me to experience how technical communication pans out for an open source project. A successful documentation project is influenced by multiple stakeholders. I am thankful for the opportunity that Google Season of Docs and CircuitVerse has given me. It has instilled in me more confidence about my skills and I look forward to my next technical writing gig.

comments powered by Disqus