Tag: patterns

How Principal Engineers Shape Documentation as a Product + Punch List Lagniappe

I’ve written plenty about documentation already (just recently here and here), so consider this a continuation of that thread. If you missed the earlier pieces, I’ll drop placeholders for them at the end. For now, let’s talk about a role that quietly makes or breaks the whole idea of “documentation as a real product” inside an engineering organization: the principal engineer.

People love to treat documentation like something you toss over the wall to a tech writer or leave in a Jira ticket until someone “has time.” A principal engineer doesn’t get to play that game. If anything, they’re the last person who can afford to pretend docs are an afterthought, because they’re the ones who end up carrying the blast radius when those docs fail. And they will fail if the principal engineer isn’t shaping them with the same rigor they apply to architecture, APIs, and operational design.

A principal engineer isn’t writing every page. They’re not your documentation vending machine. What they do is far more structural. They set the expectations for how documentation fits into the engineering lifecycle. They define the standard for what good looks like. They remove ambiguity. They make it impossible for other engineers to shrug and say, “I didn’t know that needed to be documented.” And they act as the connective tissue between engineering, product, and whoever else depends on what the system actually does versus what people assume it does.

Continue reading “How Principal Engineers Shape Documentation as a Product + Punch List Lagniappe” →

10 Best Practices IMHO for GraphQL

Here are 10 best practices for GraphQL accrued from dozens of GraphQL API implementations:

  1. Keep your schema simple: Design your GraphQL schema with a clear and concise structure. Avoid unnecessary complexity and keep it focused on the specific requirements of your application. One great idea is to implement consistent standards to keep your schema simple, read more about those ideas here.
  2. Think about the client’s needs: GraphQL allows clients to specify their data requirements precisely. Collaborate with the client-side developers to understand their needs and design your schema accordingly, minimizing over-fetching or under-fetching of data.
  3. Version your schema: As your application evolves, consider versioning your GraphQL schema to ensure backward compatibility. This allows you to introduce changes without breaking existing client implementations.
  4. Use precise field names: Choose field names that accurately describe the data they represent. Be consistent with your naming conventions and avoid ambiguity to enhance the readability and maintainability of your schema.
  5. Avoid excessive nesting: While GraphQL supports nested queries, avoid deep nesting of fields as it can lead to performance issues and over-fetching of data. Optimize your schema by flattening nested fields when possible.
  6. Implement proper authentication and authorization: GraphQL does not enforce any specific authentication or authorization mechanisms. It is crucial to implement appropriate security measures to protect your GraphQL API endpoints, such as using authentication tokens, access control rules, and rate limiting.
  7. Implement pagination for large datasets: When dealing with large datasets, use pagination techniques (e.g., cursor-based pagination) to efficiently fetch and display data. This helps in improving performance and reduces the load on both the server and the client. For details on paging patterns and implementation details check out this article.
  8. Utilize data loaders: GraphQL data loaders help optimize data fetching by batching and caching requests. Implement data loaders to avoid the N+1 problem, where multiple database queries are triggered for each item in a list. Check out this post for more details.
  9. Document your schema: Provide comprehensive documentation for your GraphQL schema to assist client developers in understanding the available types, fields, and their usage. Clear documentation and standards promotes developer adoption and simplifies integration. Check out this post for more details on GraphQL standards.
  10. Monitor and optimize performance: Regularly monitor and analyze the performance of your GraphQL API. Identify and optimize slow-performing queries, implement caching strategies, and leverage tools like Apollo Engine or persisted queries to improve overall performance.

Remember that these practices may vary depending on the specific requirements and context of your GraphQL implementation. It’s always recommended to stay updated with the latest best practices and community guidelines.