Some of this is truly tech debt, they built a great API, they know it very well because they are so close to it, then they have a hard time documenting it because they waited until it was "done" to do so. It can be hard to put yourself in the mindset of the API consumer when you are the API maintainer. Similar analogy to a backend dev trying to explain a frontend experience. The fundamentals might be there, but there are nuances that will impact the experience.
I didn't mention it here, but I strongly believe a dedicated technical writer should be included early in the lifecycle to help design an experience that can be well documented.
We actually had a feature that was going to be released out of lock-step with our product. It was going to be incredibly difficult to document and even hard for developers to understand. Thankfully the release was pushed, but this is a great example of something that should be caught by someone thinking about the documentation experience, whether it's a technical writer or a developer experience professional. We want the experience with the new feature to be good, or as you put it, ripe for usage!
I wonder what could motivate and drive founders of startups and engineering managers to utilize a tech writer or dev experience proffesionals early on.
in a use case where it is an outwords facing API - I believe the motivation is greater and ROI/value in doing a great job in the docs is quite self explenatory.
I bet it is much harder to "sell" internally in a startup mentality org that is growing. Although there are various startups that turn in a matter of 1-3 years from a 5-10 personal band of "bandits"(As I call them - and myself in similar endevours) to a robust dev dept with 5 teams + and various products.
What is your take on those 2 differnt paths and the importance of proper docs in each?
Outward-facing APIs that generate revenue will always be the easier case because it feels like you can directly attribute dollars lost/gained to the overall developer experience, including docs.
I worked in Enterprise IT and there was no concept of an internal technical writer. The team that built the project wrote just enough documentation to train the support team in maintaining it after a hand-off.
Two things could happen here.
The original project team could face a number of escalations from support (often due to the support team not understanding the project codebase or not having the proper skills to maintain the code base). This would typically hurt the project team more than the support team and result in a re-architecture or redesign of the project rather than a review of supporting assets like documentation, or lack thereof.
Alternatively, the support team could request additional training or a longer hand-off, blocking the project team from moving to the next project. This would usually result in the team leads or the most empathetic members of the team pulling together training. Could it still end in the above scenario? Yes. But often with training came tons of documentation and the number of escalations scaled at a slow enough rate a revamp of the project seemed to make more sense (changing business needs, chance to upgrade tech stack, implement new security features, etc.).
What I would rather advocate for is including technical writing and developer experience earlier in the design process. Stop waiting until a code freeze at the end of your release cycle to write your docs.
Just like you would get a UI mockup early on, why not discuss API scheme design, terms used in the API and product for consistency and clarity, etc. Theoretically, this should be part of UX, but having a dedicated stakeholder participating in design time on behalf of the developer community, the less complex developer experience technical debt you should incur, including docs.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Thank you!
Some of this is truly tech debt, they built a great API, they know it very well because they are so close to it, then they have a hard time documenting it because they waited until it was "done" to do so. It can be hard to put yourself in the mindset of the API consumer when you are the API maintainer. Similar analogy to a backend dev trying to explain a frontend experience. The fundamentals might be there, but there are nuances that will impact the experience.
I didn't mention it here, but I strongly believe a dedicated technical writer should be included early in the lifecycle to help design an experience that can be well documented.
We actually had a feature that was going to be released out of lock-step with our product. It was going to be incredibly difficult to document and even hard for developers to understand. Thankfully the release was pushed, but this is a great example of something that should be caught by someone thinking about the documentation experience, whether it's a technical writer or a developer experience professional. We want the experience with the new feature to be good, or as you put it, ripe for usage!
I wonder what could motivate and drive founders of startups and engineering managers to utilize a tech writer or dev experience proffesionals early on.
What is your take on those 2 differnt paths and the importance of proper docs in each?
Outward-facing APIs that generate revenue will always be the easier case because it feels like you can directly attribute dollars lost/gained to the overall developer experience, including docs.
I worked in Enterprise IT and there was no concept of an internal technical writer. The team that built the project wrote just enough documentation to train the support team in maintaining it after a hand-off.
Two things could happen here.
The original project team could face a number of escalations from support (often due to the support team not understanding the project codebase or not having the proper skills to maintain the code base). This would typically hurt the project team more than the support team and result in a re-architecture or redesign of the project rather than a review of supporting assets like documentation, or lack thereof.
Alternatively, the support team could request additional training or a longer hand-off, blocking the project team from moving to the next project. This would usually result in the team leads or the most empathetic members of the team pulling together training. Could it still end in the above scenario? Yes. But often with training came tons of documentation and the number of escalations scaled at a slow enough rate a revamp of the project seemed to make more sense (changing business needs, chance to upgrade tech stack, implement new security features, etc.).
What I would rather advocate for is including technical writing and developer experience earlier in the design process. Stop waiting until a code freeze at the end of your release cycle to write your docs.
Just like you would get a UI mockup early on, why not discuss API scheme design, terms used in the API and product for consistency and clarity, etc. Theoretically, this should be part of UX, but having a dedicated stakeholder participating in design time on behalf of the developer community, the less complex developer experience technical debt you should incur, including docs.