The hottest Documentation Substack posts right now

And their main takeaways
Category
Top Business Topics

🏞 Newsletter #27: take the power, scale without drowning, automate your documentation...

Women On Rails Newsletter - International Version • 0 implied HN points • 15 Mar 22
🕹 Technology Web Ruby CSS Documentation Coding
  1. The importance of changing the traditional definition of power to allow women of color to access leadership roles
  2. Tips and experiences shared on scaling a company during rapid growth periods
  3. Solutions to automate documentation to ensure good and thorough documentation in software development

Automate Production in Three Steps!

Certo Modo • 0 implied HN points • 07 Sep 23
🕹 Technology Automation Documentation Tools Features Production
  1. Automating manual tasks is crucial for growth, as manual work can consume time needed for innovation and advancement.
  2. Runbooks, as documented step-by-step instructions, are key to delegating work, reducing single points of failure, and ensuring consistency in task execution.
  3. Converting manual scripts into full-fledged software services allows for instant and automated task completion, improving efficiency and reducing human involvement.

Running Successful Engagements

Certo Modo • 0 implied HN points • 28 Mar 23
🕹 Technology Team Collaboration Documentation Feedback
  1. Identify and maintain a relationship with the team's point of contact to ensure clear communication and accountability.
  2. Prior to starting an engagement, conduct initial discovery to understand the team's operational needs and potential risks.
  3. Create a clear engagement document outlining goals, expectations, and metrics for success, ensuring alignment with the team's objectives.
Get a weekly roundup of the best Substack posts, by hacker news affinity:

RDEL #18: Can better documentation come at a cost for some teammates?

Research-Driven Engineering Leadership • 0 implied HN points • 13 Nov 23
🕹 Technology Documentation Team performance Job Satisfaction Burnout
  1. Improved documentation quality lifts every technical capability measured in teams.
  2. Better documentation decreases burnout and increases job satisfaction and productivity, but can lead to increased burnout for underrepresented teammates.
  3. Recognizing the importance of documentation's impact and managing distribution of 'glue work' can help improve team performance and well-being.

Software Projects: Sink or Swim

Bismuth • 0 implied HN points • 14 Jun 24
🕹 Technology Software Testing Documentation Technical Writing Project management
  1. Establishing and maintaining consistent patterns in a software project is crucial for long-term maintainability and success.
  2. Thorough testing, especially of core business logic and high-risk features, is essential to prevent bugs and ensure code maintainability over time.
  3. High-quality documentation is vital for attracting users, helping new contributors, and ensuring the long-term success and growth of a software project.

Documentation is Hard

Tribal Knowledge • 0 implied HN points • 29 Oct 22
🕹 Technology Software Development Documentation Engineering Coding Startups
  1. Documentation often gets neglected in fast-paced environments like startups due to time constraints and prioritization of immediate tasks.
  2. In software development, trade-offs are inevitable, and sometimes opting for 'good enough for now' is a valid choice to balance business needs with engineering solutions.
  3. Documentation should focus on improving code readability, saving time for both current and future developers, and should be informative yet concise to serve its purpose effectively.

My Knowledge Is Your Knowledge

Tribal Knowledge • 0 implied HN points • 21 Mar 22
🕹 Technology Software Development Startup Documentation Onboarding Community
  1. Tribal knowledge refers to information known within a group but not outside of it, commonly seen in fast-moving teams like startups where documentation might be lacking.
  2. Onboarding new team members to a system built on tribal knowledge can be challenging and time-consuming, taking up to 6 months for full understanding.
  3. Building a community to share collective knowledge can help individuals survive and thrive in various fields by leveraging unique experiences and backgrounds.

Good Engineer, Good Writer

Tech Ramblings • 0 implied HN points • 04 Aug 24
🕹 Technology Software Engineering Communication Documentation Career
  1. Good communication is key in software development. When you clearly explain your ideas, it makes teamwork smoother and reduces confusion.
  2. Writing concise documents helps you focus on the main problem and solution. Keeping things short and to the point makes everyone understand better.
  3. Using visuals can make complex ideas easier to explain. Sometimes a picture can communicate things more effectively than just words.

The Comprehensive Guide to Architectural Decision Records

Curious Devs Corner • 0 implied HN points • 11 Jul 24
🕹 Technology Software Architecture Documentation Development Engineering
  1. Architectural Decision Records (ADRs) help document important decisions in software architecture, including why certain choices were made. They're like notes that anyone on the team can review later.
  2. Using ADRs boosts team trust by providing clear reasons behind technology choices, reducing confusion, and helping new members understand past decisions. They show what has been discussed and why certain technologies were selected or rejected.
  3. ADRs promote transparency by allowing anyone interested to see the decision-making process. This helps different teams learn from each other and fosters better communication.

When Looking Back at Legacy Code, All You Really Want to Think Is: "This Is Reasonable"

Andrew’s Substack • 0 implied HN points • 16 Oct 24
🕹 Technology Software Development Programming Technical Debt Documentation
  1. Legacy code should be clear and understandable. The goal is for developers to look back at it and think, 'This makes sense.'
  2. Good legacy code is simple, consistent, and has clear documentation. This helps new developers quickly understand it without getting lost.
  3. Investing time to write clear, well-documented code saves headaches later. It makes maintenance easier and helps new team members get up to speed faster.

Create a simple data catalog with Sort, Postgres, and Markdown

Database Engineering by Sort • 0 implied HN points • 04 Nov 24
🕹 Technology Data Management Database Systems Documentation Software Tools Open Source
  1. Using Sort, Postgres, and Markdown together makes it easy to create a simple data catalog. This setup helps you organize and describe your data clearly.
  2. Markdown is great for writing human-readable documentation that explains your database tables, their columns, and how to use them. It helps everyone understand the data better, even without deep SQL knowledge.
  3. With this method, team members can quickly run queries and find the data they need. It's a flexible way to collaborate without complicated setups or high costs.

Selectively Serving Your API Reference

The API Changelog • 0 implied HN points • 07 Feb 25
🕹 Technology API design Web Development Software Engineering Documentation
  1. You can create an API reference that adapts to different users, offering both a human-friendly and machine-readable version. It's important to meet the needs of both audiences.
  2. Using an OpenAPI document makes it easy to generate a comprehensive API reference without much effort. It's like having a complete guide available for your API.
  3. Content negotiation allows you to serve the right version of your API reference based on the request type. This way, humans get a readable document, while machines receive the necessary JSON data.