New to Inkdrop
Key note categories and examples for tech issues
To practice the issue-driven tech note-taking method in Inkdrop, it'd be nice to know the key categories for tech issues you might encounter in your workflow. This page provides several real-world examples for each category so you can get a better idea of when and what to write in your notes.
As we discussed on this page, Inkdrop has an opinionated note-taking workflow that encourages you to focus on writing one note per issue, while managing them as tasks with note statuses. This workflow would help you effectively build your knowledge base while keeping track of your progress and tasks. However, if you are new to software engineering, it might still be unclear what kind of issues or information you should document. So, this guide aims to clarify when and what to write, with real-world example notes across 9 key issue categories.
You don't have to cover everything listed in the 'What to write' section in each category because your tech notes aren't meant to make you look good or akin to homework reports; They are merely examples to inspire you. You can just jot down what you think is necessary in your coding workflow.
Small projects
Every project starts from small. Avoid trying to construct a beautifully organized and completely structured knowledge base from the beginning. Instead, just write your idea and process in a single note. If it starts bloating up, it's time to split it into multiple notes for each issue type.
- When to take: When you start a new side project, hobby thing, or just a proof-of-concept of your idea
- What to write:
- Brief description of the project idea
- Goals or objectives you want to achieve
- Research notes on relevant technologies, libraries, or tools
- Step-by-step process or approach you plan to take
- Code snippets, prototypes, or experiments
- Challenges or roadblocks encountered
- Lessons learned or insights gained
- Future improvements or next steps
- Examples:
Bugs
Document any defects, errors, or unexpected behaviors encountered in the software or system.
When to take: Whenever a bug is discovered during development, testing, production use, or reported by end-users or customers
What to write
How to reproduce the bug
- Code snippets
Expected behavior/output and actual behavior/output, including:
- Error messages, stack traces, or error codes, along with the context when they occurred
Environment/platform details
- Operating system (name and version)
- Hardware specifications (CPU, RAM, GPU, etc.)
- Browser (name and version, if applicable)
- Mobile device (make, model, and OS version, if applicable)
Application/tool version numbers
- The version number or build number of the application, tool, or system in which the bug was encountered
Screenshots
- Visual aids can be helpful, especially for user interface or visual bugs
Links to related issues, documentation, or forums
Process to research, potential solutions, and result:
- Document the steps taken to investigate and research potential solutions for the bug, including any findings, workarounds, or unsuccessful attempts.
Link to a pull request for the bug fix:
- If a fix for the bug is implemented, include a link to the pull request or commit that addresses the issue. This can provide valuable context and allow others to easily reference the code changes.
Examples
Feature ideas
Capture ideas for new features, enhancements, or improvements
- When to take: During brainstorming sessions, based on user feedback, or when identifying gaps or opportunities, or when taking a bath and suddenly an idea comes to you
- What to write:
- What problem the feature would solve
- Context for why it's essential
- User stories/use cases
- How/when users will interact with the feature
- Potential implementation details
- Required technologies, APIs, or libraries
- References
- Similar features in other apps
- Screenshots
- User feedback or reviews
- What problem the feature would solve
- Examples
Learning tasks
Document step-by-step instructions for completing specific tasks or procedures
- When to take: When trying to figure out how to do something technical, or learning/documenting a new process, setting up environments, or performing recurring tasks
- They can serve as a reference that you can use to complete the task again in the future
- What to write:
- Individual steps required to complete a specific task
- Prerequisites
- Commands
- Expected outcomes
- Troubleshooting tips
- Relevant screenshots or code snippets
- Examples:
Research topics
Capture information, findings, or insights gained from researching specific technologies, libraries, or techniques related to the project
- When to take: While researching on a particular technology or concept
- e.g., frameworks, libraries, programming languages, algorithms, or techniques related to your project
- What to write:
- References to documentation or resources
- Comparisons
- Pros and cons
- Key findings
- Any conclusions or recommendations
- Examples:
Troubleshooting issues
Document the process of diagnosing and resolving issues or problems encountered during development or deployment
- When to take: When you're trying to resolve an issue with a piece of technology that arises during development, deployment, or maintenance of a system or application
- What to write:
- What happened
- Error messages, symptoms, or unexpected behavior observed
- Investigation process
- Reviewing logs, running diagnostic tools, testing hypotheses, or consulting documentation or online resources
- The steps you've taken to troubleshoot the problem
- This can help you keep track of what you've tried and what has or hasn't worked.
- What happened
- Examples
Configurations and tips
Document the configurations, settings, or customizations made to the development tools, IDEs, editors, or applications used in the software development process.
- When to take:
- When setting up or configuring development environments, tools, or applications for the first time.
- When making significant changes or tweaks to existing configurations.
- What to write:
- Configuration details (e.g., database connections, API keys, file paths)
- Environment-specific settings
- Any specific instructions or considerations
- Example of tools/applications where configuration notes can be useful:
- Code editors (e.g., Neovim, Visual Studio Code, Sublime Text)
- IDEs (e.g., Xcode, Android Studio, IntelliJ IDEA)
- Version control systems (e.g., Git, Mercurial)
- Build tools (e.g., Make, Gradle, Maven)
- Shell environments (e.g., Bash, Zsh)
- Database clients or administration tools
- Browser developer tools
- Examples:
Performance optimization
Document performance bottlenecks, optimization strategies, and techniques used to improve the efficiency or scalability of the software or system
- When to take: During performance testing, profiling, or when addressing performance issues.
- What to write:
- Performance metrics, bottleneck identification
- Optimization techniques applied
- e.g., caching, code refactoring, database indexing
- Results or improvements achieved
- Any ongoing monitoring or considerations
- Examples:
Operation procedures/logs
Capture information related to the preparation, deployment, maintenance, and operation of the software or system, as well as logging procedures and practices.
- Preparation
- When to take: During the planning and preparation phase before deploying or maintaining the software or system.
- What to write:
- Deployment prerequisites (e.g., hardware requirements, software dependencies)
- Environment setup instructions (e.g., configuring servers, load balancers, databases)
- Backup and recovery procedures
- Monitoring and alerting setup (e.g., metrics to track, alert thresholds)
- Scaling or load balancing strategies
- Security considerations (e.g., access controls, encryption)
- Rollback or rollforward plans
- Logging
- When to take: During the actual deployment, maintenance, or operation of the software or system.
- What to write:
- Deployment steps and execution logs
- Configuration changes or updates made during deployment or maintenance
- Issue or incident reports (e.g., outages, performance degradation)
- Troubleshooting steps and resolutions
- Monitoring logs and performance metrics
- Backup and restoration logs
- Any operational challenges or lessons learned
Other types
This list wouldn't limit what you can write in Inkdrop.
Other possibilities would be:
- Meeting notes
- Draft blog articles
- Journals
- Reading notes
- Code reviews
- etc.
Just note that Inkdrop is a plain-text Markdown editor, which may not fit every type of note but would work best for coding-related notes. This is because of the decision of 'The right tool for the right task' philosophy. So, you might want to consider using another app for writing non-linear thoughts and image-heavy notes.
Get help