Getting Started
Intro
CodeTrail helps engineering teams effortlessly capture and update their knowledge, ensuring that everyone is always on the same page. We do this by bringing documentation closer to the codebase, making it easy to write and update documentation as you work.
Demo
Use Cases
CodeTrail helps engineering teams communicate more effectively by making it easy to write and update internal documentation. Here are some of the ways you can use CodeTrail:
- Onboard new hires with personalized onboarding Stories
- Document your codebase with inline documentation
- Discuss and document design decisions with one-off Stories
- Get feedback on your code with code review Stories
All of these use cases benefit from proximity to the codebase, which is why CodeTrail is built to be integrated into your development workflow from day one.
Setting up CodeTrail
Installing CodeTrail for your IDE
To set up your IDE and codebase to work correctly with CodeTrail, see the installing IDE extensions
guide. CodeTrail works with any git-based codebase. If you desire to use CodeTrail for projects that don't use git, please let us know.
Composing and Playing Stories
Composing your first Story
To compose a Story in your IDE, navigate to a location in your codebase you want to document. Select the code you want to document, then right-click and select CodeTrail: Annotate... or press Ctrl+Shift+A (or Cmd+Shift+A on Mac) for VS Code. This will open the Annotate window.
After you have added some content to your Annotation, you can click Add and continue to add more Annotations to your Story, or Complete Story to finalize and publish your Story.
You can add multiple Annotations from multiple repositories to a single Story. Each Annotation will remember the repository, branch, and commit hash it was created from, so you can always go back and see the code as it was when the Annotation was created.
Once you're ready to publish your Story, click Complete Story. CodeTrail will open the Story in your browser, where you can review it before publishing it to your Workspace. To publish your Story, click Publish, enter a title and confirm. Your Story will now be visible to everyone in your Workspace.
You can copy a permanent link to your Story by clicking Copy Link. This can be added to your knowledgebase, pull request, issue tracker, Slack, or anywhere else you want to share your Story.
Playing a Story
To play a story, open the Story link in your browser, then click Open in Desktop. If this is the first time you have played a Story for this repository, you will need to locate the repository on your machine. If you have not cloned the repository yet, follow the instructions to clone it. Once you have done this, CodeTrail will open the Story in your IDE of choice.
Security
When using the CodeTrail IDE extensions, your documentation and annotations reside within your codebase. CodeTrail IDE extensions do not upload any data.