Tips for Creating Strong Documentation

🔥 Auditing a client’s #ERG documentation this morning, and whew… had some thoughts. Sharing major takeaways in case it helps 👇🏾 🔑 Your ERGs don’t rise to the level of your expectations—they fall to the level of your documentation. Here were some of the common themes of the feedback that I gave him: 📣 Tone matters. Your documentation sets the culture. 📂 Frameworks + templates > suggestions + articles. Make it plug-and-play. 📖 Think comprehensive handbook, not a scattered toolkit. ✍🏿 Simplified language = expertise + consideration. Overcomplication is a 🚩. 🎨 Visuals are your friend. Make it digestible. 📍 Centralization is a major key. One source of truth saves everyone time. 🚫 Beyond closing the loop—don’t create a problem. Only present solutions. 🔄 Leadership succession should be handled at a program-wide level. Efficiency over scrambling. 📌 The more specific, the better. Not “reach out to ___”, but “here’s a message template & timeline for when you reach out to ___.” 🛠️ Structure is discipline. Give your leads something solid to work from. ❌ Remove ‘work for work’s sake.’ Busywork isn’t impact. 📝 Docs with visuals > pretty slides (especially text-heavy slides). 🔍 Optimize for findability. Next level from “searchability.” ⚖️ Yes, leads are volunteers, but this is a company program. Take the reins back. 🎯 Get more granular. Details remove confusion. 📊 Success articulation + metric system creation should NOT be on the leads. That’s a program responsibility. 💡 By the numbers, this is already a solid ERG program. Imagine what they could unlock with even more clarity. 🚀 - The ERG Homegirl ✌🏿

1/You won’t remember what you did. Not next week. Not next month. Write. It. Down. It will save your future self hours—days. 2/ Documentation seems like a waste of time. Until you stare at a directory named results_final_final2_revised. And ask, “What even is this?” 3/ Bioinformatics is messy. You run 15 commands. One of them works. You move on. But in 6 months, you'll need to re-run it. And you won't remember which one. 4/ Build the habit: Keep a README for every project One per data folder: where it came from, when, how Write every working command right after it works 5/ Yes, right after it works. Not "I'll do it later." Later becomes never. Your shell history won’t save you forever. 6/ Seven years ago, I documented how I processed enhancer-promoter interactions. Still usable. Still makes sense. https://lnkd.in/e4nBvBCb 7/ Nine years ago, I wrote down my scRRBS (single-cell DNA methylation) processing pipeline. Still helping me today. https://lnkd.in/eHTNb4pQ 8/ You don’t need to write essays. Just enough that a confused version of you can follow along. And trust me, they will be confused. 9/ Use comments in your code. Use markdown for notes. Use Jupyter or Quarto for literate workflows. Don’t leave your brain in your shell history. 10/ Why document? Reproducibility Debugging Collaboration Sanity Growth Your README is your lab notebook. 11/ You think you’ll remember. You won’t. You think it’s clear now. It won’t be. You think it’s just a small hack. It’ll become the foundation of your next pipeline. 12/ Key takeaways: Document as you go, not after A good README is future-proofing Your notes are your superpower Even if no one else reads them, you will 13/ Final word: Documentation isn’t a burden. It’s a record of your thinking. It’s your bioinformatics memoir. And yes—it’s part of the science. I hope you've found this post helpful. Follow me for more. Subscribe to my FREE newsletter chatomics to learn bioinformatics https://lnkd.in/erw83Svn

🛠️ In my last post, I shared 7 reasons why data documentation is still so hard. Now let’s talk solutions: Here’s how leading data teams are solving each challenge today: 1. It’s no one’s core responsibility → Make documentation part of the workflow. Don’t allow dbt model PRs to merge without a model description. Treat documentation like tests—required for production. 2. Data is always changing → Use automated lineage and change detection. Get alerted when upstream tables or columns change. Use AI to auto-update or review the new docs. 3. Manual documentation doesn’t scale → Leverage AI to generate table and column descriptions. Start with smart defaults based on naming patterns and SQL logic. Let humans review and refine. 4. Your tools are fragmented → Adopt a centralized metadata platform. One place that connects your warehouse, dbt, BI tools, Airflow, ... so you can see the full picture. 5. Documentation is hard to find → Bring docs to where people work. Show table descriptions in query editors. Surface lineage in BI tools. Make metadata searchable in Slack. Metadata platform can help bringing documentation to tools that users are already working with. For example, Select Star has chrome extensions, Slack apps, and MCP server, that will display the relevant information within the apps. 6. No feedback loop → Track usage and engagement. See which docs are viewed or ignored. See which data assets are being viewed. Let users comment or flag stale content. 7. Lack of ownership → Assign data owners by table, dashboard, or metric. Use metadata tools to operationalize the data stewardship. Notify owners to review/update docs, when questions get asked, when things go out of date. Good documentation is no longer about extra work. With AI and metadata automation, it can be integrated into how your team already works. This is exactly what we’re building at Select Star—drop me a message if you want a look. Anything I missed? Also happy to elaborate more on any of the points.

In cybersecurity, technical skills get you noticed, but soft skills keep you valuable — especially when it comes to incident documentation. When I started writing up incidents, I used to just list logs and alerts. But that didn’t help anyone — not my team, not management, and definitely not future investigations. Over time, I’ve learned a better way: What Makes Good Incident Documentation? Clear Timeline: Start with when the incident started, how it was detected, and what steps were taken — in order. Plain English Summary: Write a short, non-technical paragraph anyone can understand. (Think: “The attacker tried to log in 4 times using a brute-force method.”) What Was Affected: List impacted hosts, services, or users — even if it's just “attempted access” and nothing was successful. How It Was Handled: Include what actions were taken (e.g., blocking IPs, isolating machines, resetting credentials) and who took them. Lessons Learned: Every incident teaches something. Did you improve a detection rule? Update documentation? Add a new alert? Pro Tip: Use consistent formatting. I personally use this structure in our reports: 1. Summary 2. Detection Method 3. Root Cause 4. Affected Assets 5. Response Steps 6. Outcome 7. Recommendations Why It Matters Good documentation: Makes handoffs easier Builds trust with stakeholders Helps train new analysts Supports compliance and audits Saves your team time when it happens again Have you seen a great (or bad) incident report before? Let’s share tips on how we can all document better. Because in security, clarity is part of defense. #CyberSecurity #IncidentResponse #SoftSkills #SOCAnalyst #BlueTeam #DocumentationMatters #IRProcess #SecurityOperations #InfoSec #WritingSkills

Want to clean up your data, create better processes, get better insights, and speed up future work? Start documenting your ops process, especially within your CRM. What do I mean by this? Create a Google sheet and: ✔️ Note (most) fields, especially custom fields ✔️ What they mean ✔️ How they're set ✔️ When they were created ✔️ When they were last edited (and by whom) ✔️ Any applicable notes ✔️ Double bonus points if you create a tab for reports to use, where they're used (this is how we report x to the board, etc.), and what they mean (Then, share this document and make it readily accessible to everyone.) This is especially needed in scale-up companies while you're onboarding more and more employees. You may be thinking, "Woah, Ashley! That's overkill. I don't have time for that!" ...At least, that’s what I would be thinking. I get it. I used not to like documentation or internal process; I thought it was clunky, unneeded, and slowed everyone down. Then I saw (and continue to see) the headaches the lack of process and documentation can cause and how much it slows down work. And time is money. 🙃 So why is this so important? ✅ Often, in companies, there are a lot of legacy fields that don't mean what they should. So this will send others down rabbit holes that aren't fruitful. Or, there are custom fields that others may not be aware of. ✅ It lessens distrust in data. This is a huge topic I could talk a lot about, but when your team is constantly questioning if that report or field is correct, you're missing out on working time. ✅ It creates consistency. Every time you look at ACV, you know it's correct because you've documented it. ✅ It ensures your fields are held accountable for being cleaned up + reviewed by seeing when they were created & last updated/reviewed. (I highly recommend reviewing this 2x/year or quarterly.) ✅ It empowers your team and aids in training Spinning this up definitely takes time, but it saves time down the road. It allows your team to work faster and is huge for onboarding + training. A nice lil’ bonus point here is it begins to uplevel your knowledge in marketing ops, which is a top skill within successful marketers. Does anyone have a document like this that they've created or used?

How I maintain clarity in my code even with 20+ contributors: Do you find yourself staring at your own code, asking "Who wrote this terrible mess?" Even though you know it was you? You’re not alone. Poor documentation is a real headache even for a senior dev. With these 5 steps, you can avoid wasting hours trying to understand what your code means: 1. Create an Overview: Start with the project's purpose. This helps everyone stay on the same page from the beginning. 2. Detail Your Process: Break down your code step-by-step. This way, you won’t waste time rediscovering your own logic. 3. Include Visuals: Use charts or screenshots to illustrate key parts of your process.  A picture is worth a thousand lines of code!     4. Highlight Challenges and Solutions: Share what problems you faced and how you solved them. This not only showcases your problem-solving skills but also builds trust with your team. 5. Summarize Results:     Focus on outcomes and insights for business stakeholders, while also pointing out areas for further improvement for your fellow developers. Structure it like this: Introduction > Objectives > Methods > Results > Conclusion > Future Work. Clarity is key. Remember, understandable code is valuable code. Repost if you can relate to Sheldon ♻️ PS: Don’t be like Sheldon, don’t skip the manual! PPS: When was the last time you didn’t understand your old code?

How I Turn Every Project Into a Productivity Powerhouse Ever feel like your productivity vanishes halfway through a project, no matter how motivated you start? You are not alone. I have been there, too. Managing multiple projects can quickly become overwhelming. Details slip through the cracks, documentation piles up, and suddenly, you are spending more time searching for information than actually moving things forward. What is worse? That sinking feeling when you realize you have solved the same problem three times, or can’t remember why you made a key decision last month. Sound familiar? Here is how I have turned project chaos into a repeatable, productive process without adding complexity or extra meetings: Build Once, Reuse Always: I create a simple project template that covers the essentials: 🔹Project goal 🔹Tools used 🔹Data sources 🔹Challenges & fixes 🔹Key insights 🔹Recommendations Every new project starts with this template, so I never reinvent the wheel. I can tweak the template occasionally, but the above points remain the foundation. To be more precise, I … 🔹Document in real-time: I jot down decisions, challenges, and solutions as they happen, not at the end. This keeps details fresh and saves me from “what was I thinking?” moments later. 🔹Screenshot shortcuts: A quick screenshot is worth a thousand words. I capture key steps, errors, or milestones, so I have a visual log of what happened and when. 🔹Centralize and keep things related to each project in the same space: Everything, including notes, screenshots, and templates, lives in one clearly named folder. No more hunting through endless files or emails. These habits keep me productive, but they also help me deliver better results faster and with less stress. If you want to level up your project game, try them. PS: How do you stay productive? Repost ♻️ so others can learn. ---------------- I am Edwige a Data Analyst who can help you turn your messy data into actionable insights. DM me to get started. ----------------