Skip to content

Update Pragati_UserOnlineDocumentation.md #47

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update Pragati_UserOnlineDocumentation.md #47

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 21 additions & 36 deletions content/posts/Pragati_UserOnlineDocumentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@


---
title: "User Documentation: Final Report (GSoD 2020 - Pragati)"
date: 2020-12-02T14:17:50Z
Expand All @@ -13,29 +15,27 @@ url: "/posts/Pragati-user-online-documentation/"
### Overview


My project focused on creating videos and documentation for CircuitVerse (CV) User Documentation. This documentation encompased 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.

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 Original Proposal

### 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 CirucitVerse platform, the videos played a key part in improving the onboarding 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.

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.**Explain 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.
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.

Using the available assets in Camtasia, I created different artaffects for including in the videos. Once these artaffects were created, they were rescued across different videos for brand building. Each video tutorial
**Link to video:** <a href="https://www.youtube.com/watch?v=3Df-2Cn_80A&feature=youtu.be">Introduction to CircuitVerse Platform: </a>
**Status of deliverable:** Complete

1. **Link to video:** Introduction to CircuitVerse Platform: [https://www.youtube.com/watch?v=3Df-2Cn_80A&feature=youtu.be](https://www.youtube.com/watch?v=3Df-2Cn_80A&feature=youtu.be)
2.**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
**Status of deliverable:** Complete

Table 1: Different videos created to explain the CV simulator

Expand All @@ -49,45 +49,33 @@ Table 1: Different videos created to explain the CV simulator
| 6 | Using Combinational Analysis Tool | This video demonstrates how the Combinational Analysis tool can be used for building a seven segment decoder | [https://youtu.be/kl9GC_VxAcU](https://youtu.be/kl9GC_VxAcU) |
| 7 | Saving Projects Within The CircuitVerse Simulator | This video demonstrates how the circuits can be saved using the CircuitVerse platform | [https://youtu.be/b4SXde9huFQ](https://youtu.be/b4SXde9huFQ) |

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.

3.**New UI Revamp Documentation:** While videos improve the onboarding 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 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.


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:
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: <a href="https://docs.google.com/document/d/1RX_jaWR9lm_vdr2yu8MsrBMzwGeVJZx_RG4kwdlgZeI/edit?ts=5fc91e4c#heading=h.88yx503a89fx"> CV User Online Documentation</a>**


**Link to guide: **<a href="https://docs.google.com/document/d/1RX_jaWR9lm_vdr2yu8MsrBMzwGeVJZx_RG4kwdlgZeI/edit?ts=5fc91e4c#heading=h.88yx503a89fx"> CV User Online Documentation</a>
**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:<a href="https://docs.google.com/document/d/1RX_jaWR9lm_vdr2yu8MsrBMzwGeVJZx_RG4kwdlgZeI/edit?ts=5fc91e4c#heading=h.88yx503a89fx"> CV User Online Documentation</a>**


**Link to guide:**<a href="https://docs.google.com/document/d/1RX_jaWR9lm_vdr2yu8MsrBMzwGeVJZx_RG4kwdlgZeI/edit?ts=5fc91e4c#heading=h.88yx503a89fx"> CV User Online Documentation</a>
**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:<a href="https://docs.google.com/document/d/1-Esv8pW_rTC02I09TH_aTuI2WxQYrFU4LG04jDGhLK4/edit#heading=h.k2zz91suudcb"> CV Contributing Guidelines</a>**


**Link to guide:**<a href="https://docs.google.com/document/d/1-Esv8pW_rTC02I09TH_aTuI2WxQYrFU4LG04jDGhLK4/edit#heading=h.k2zz91suudcb"> CV Contributing Guidelines</a>
**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:
Expand All @@ -104,21 +92,18 @@ This project allowed me to gain experience using a variety of different technolo
# 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.
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.
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.