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.
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.