ViDoc: An Interactive Documentation Extension for Visual Studio Code
Vision StatementIn modern software development, clear and comprehensive documentation is key. ViDoc is a VS Code extension that aims to revolutionize how documentation is done by incorporating audio-visual elements directly into your code. The extension enables users to record their screen, providing real-time context and commentary on their actions. The result? Documentation that feels like a pair-programming session. ViDoc aims to promote collaboration, enhance code comprehension, and simplify the documentation process by providing an intuitive, engaging and interactive way to explain complex code snippets. Rather than just reading about how a piece of code works, ViDoc allows you to show, tell, and share in a more dynamic way. When to use VidocVideo's are a bit like voice-messages. People love to send them but don't like to receive them. It is a sender-friendly medium not a receiver-friendly medium. This gives some hints on when we think it should be used: Do's:
Don'ts:
Simple introduction videoStoring video recordings within the repositoryhttps://github.com/bubblegumsoldier/vidoc/assets/3788628/7dc62d0a-b92e-4404-905e-ea946da3a70f The easiest way to try out the extension is to store the files locally inside the repository. No configuration file is needed in order to achieve that behaviour. However, this is not recommended for larger projects as it can substantially increase the repository size and pushing videos as well as pulling videos can be a pain. Setting up Vidoc.Cloudhttps://github.com/bubblegumsoldier/vidoc/assets/3788628/bc755396-4757-40b7-a7e1-a49bebcd8a29 Vidoc.Cloud is a streamlined, open-source hosting platform under the domain In order to configure Vidoc to use vidoc.cloud follow these steps:
When you are recording your first Vidoc you will be asked to log into your account. From then on your vscode user is synced with your Setting up Vidoc with AWS (advanced configurations)https://github.com/bubblegumsoldier/vidoc/assets/3788628/19a3ce1b-db8f-461f-a7cd-76a68bf50147 This guide walks you through setting up AWS S3 video upload for your VSCode extension. You can also configure it to work with other S3-compatible providers like DigitalOcean. Prerequisites for using S3 Storage
Configuration FilesYou need to create two files in the root directory of your project:
Important: Make sure to add .vidocconf.jsonThis file contains the configuration details for saving videos and performing post-processing operations. Example
.vidocsecretsThis file will store your AWS secret information. Replace the placeholders with your actual AWS information. The placeholders correspond to the variables you have referenced in your Example .vidocsecrets:
Configuration OptionsHere's a brief overview of what each field in the configuration means:
Removing unused videosLet's say you have just pressed record and recorded a video that was not on the standard of quality you would like. So you remove the newly generated vidoc metadata file. But the file has already been uploaded. This can happen frequently and your S3 Bucket fills up over time with unreferenced videos. To "garbage-collect" these files you can run the command The command will find in the bucket all files for which there is no vidoc metadata file in this repository under Caution! If you are using the same bucket for another repository then it would remove the videos that are referenced there. Create a new bucket for each repository! Caution 2! Remember that Vidoc can only see what Vidocs are on your branch. If a colleague has added a Vidoc in another branch you might just be removing it for him. Tipps and TricksPause Videos oftenOftentimes you might find yourself stumbling over words or trying to formulate the same idea in different ways. Sometimes it makes sense to pause the video, think about the best formulation and resume once you have settled on the easiest formulation to bring your point accross. Usage of WhiteboardsYou can simply install an extension such as tldraw or Excalidraw to share a whiteboard while recording. There are three ways to incorporate whiteboards and diagrams into your videos:
All three will greatly improve the quality of your videos. Overlay your browser or other windowsWhen you start recording a Vidoc, the area of your VSCode window on the screen will be fetched. The area on your screen is recorded. Different to sharing a specific window in Google Hangouts, Zoom or Teams, any overlay over the window will also be captured. You can use this feature to
Build Onboarding Guides using markdownVidoc was specifically optimized to work in Markdown files. This allows you to build great Onboarding guides for new developers by incorporating a mix of text + videos while keeping the footprint of these files as minimal as possible. Contribution GuidelinesWe welcome contributions from the open-source community. To contribute:
Please ensure your Pull Request adheres to the following guidelines:
Thank you for your interest in improving ViDoc! Introduction Vidoc CodeLicenseThis project is licensed under the MIT License - see the LICENSE.md file for details. |