Tips for Maintaining Engineering Documentation

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

Want to make your technical #documentation more effective? Keep it skimmable! I've found that using short, simple sentences and compact paragraphs makes documentation infinitely more useful for readers. When developers need answers, they scan documentation quickly, looking for specific information. By breaking content into clear sections with descriptive headings, you create natural "jumping-off points" that help readers navigate directly to what they need. Think of good headings as signposts guiding your readers through the content. Simple language and concise paragraphs reduce cognitive load, making your docs easier to understand, especially for non-native English speakers (which is an added accessibility win). Remember: technical documentation isn't creative writing. Its purpose is to convey complex information clearly and efficiently. #TechnicalWriting #Documentation #DeveloperExperience #TechComm #WritingTips #technicalwriter #InformationDevelopment #InformationDeveloper

In any data analytics project, documenting your work will save a lot of headaches in the long run. One of my favorite ways to do that is by using my a well written README file. Think about the README file as a “fools proof” recipe, where anyone can read and understand what your project is about. Here is what you can include: ⭐️ Project Overview: Start with a description of what the project goals are. In here you can put the scope of your analysis. ⭐️ Data Sources: Provide an overview of where the data comes from. This is specially helpful if you have multiple sources of data. ⭐️ Project Structure: Explain the organization of the project’s files and directories. This helps users know where to look for scripts, datasets, and outputs. ⭐️ Assumptions and Limitations: State any assumptions made during the analysis and acknowledge the project’s limitations, such as data quality or model constraints. ⭐️ Version Control: Maintain records of code and dataset versions to track changes and revert if necessary. ⭐️ ETL/Processing Pipelines: Document each step in data extraction, transformation, and loading processes, including the rationale behind any data cleaning, filtering, or transformation decisions. ⭐️ Business Logic: Clarify how the data connects to the business logic. For instance, how missing data is handled or the logic behind specific business rules applied to the data ⭐️ Analysis and Insights Documentation: Be clear about how the analyses was performed, which models were used, and how that relates to the project goals. This helps future users or team members understand how conclusions were reached. A solid documentation takes time. Remember that those tips are good not only for your coworkers, but your future self will also thank you Be curious and keep on nerding 😊

Don’t fall for this common trap: Putting off the documentation until the end of a project. It just won’t get done if you do. Or it won’t be as detailed or complete as it should be. If you document your code along the way, you’re much more likely to remember important details and it’ll actually help you get the project done faster. What does documentation look like? — Comments on your CTEs describing why you needed one — Comments documenting any changes from the norm — Decriptions of functions you create — Updating the ticket with time spent and current tasks — My favorite: a log at the top of every query and script that outlines any changes people come in and make through the lifecycle of the code. Spend the time to document along the way. Trust me, I’m not good at remembering to do this 🤦🏻♂️ I did the bare minimum documentation before leaving on vacation this week. I don’t look forward to jogging my brain on Monday morning 😂