3 ms·

Whoa hey wait, could you expand on this culture of documenting things? what were the requirements? we desperately need some culture around this, it's been terri

Whoa hey wait, could you expand on this culture of documenting things? what were the requirements? we desperately need some culture around this, it's been terrible in this remote culture to know what anything is actually about in our codebase

ebiester 4y ago
This is probably written better as a blog, so let me put in the highlights and commit to having a blog written by the end of the week at https://ebiester.com https://ebiester.com - I've written a few things about documentation but haven't addressed it as a cultural element. The basic assumption is that most developers don't hate writing documentation other than they don't feel like they do it well and don't feel like it's effective. The best way to make it feel effective is threefold - build a proper framework on which you can attach the documentation for discoverability; build an expectation for a documentation portfolio; and build it into your definition of done at the feature level;. 1. Build a proper framework. Techdocs is part of backstage and uses your own git repository to build it in markdown. https://backstage.io/docs/features/techdocs/techdocs-overview https://backstage.io/docs/features/techdocs/techdocs-overvie... has more information. Diataxis is a good start to how to think about the types of documentation. https://diataxis.fr/ https://diataxis.fr/ is what I use to separate out the types of documentation that need to be written. Most documentation in my experience is written as "explanation." Having API reference and howtos are important, and so many howtos are just built out of asking someone on slack anyway. It is a matter of saying, "you've already done the work to discover this: just put a rough draft where I've put it to be and people can refine it as they go." 2. Build an expectation of a documentation portfolio. I write about that at https://www.ebiester.com/documentation/2020/06/02/agile-documentation-takeaways.html https://www.ebiester.com/documentation/2020/06/02/agile-docu... but it was a concept written about in Agile Documentation. Start with "these are the minimum requirements for a new project" and keep it very light. Build documentation, codebase expectations, and a quick architectural tour is likely enough to start and the rest will follow. 3. Build it into the definition of done. This takes management buyin, but it means taking it into account for the schedule as technical debt originally. It will not slow you down in the end, but the activation energy of learning takes some time. But just like unit tests or manual testing, there's a set of expectations that are baked into calling something done. I think a bonus is that so much of documentation is built through our chat and email programs, and just having the courage to copy it out and clean it up a little or take videos and transcripts of debugging sessions is a good start, but it's easy to make a mess. The key is categorization.
- compacct27 4y ago
  Wow, I’m glad I asked. Thanks a ton, looking forward to the blog post!
  - ebiester 4y ago
    https://www.ebiester.com/documentation/2022/12/23/building-documentation-culture.html https://www.ebiester.com/documentation/2022/12/23/building-d... is my thoughts. Let me know if that answers the question.

ebiester 4y ago

This is probably written better as a blog, so let me put in the highlights and commit to having a blog written by the end of the week at https://ebiester.com https://ebiester.com - I've written a few things about documentation but haven't addressed it as a cultural element. The basic assumption is that most developers don't hate writing documentation other than they don't feel like they do it well and don't feel like it's effective. The best way to make it feel effective is threefold - build a proper framework on which you can attach the documentation for discoverability; build an expectation for a documentation portfolio; and build it into your definition of done at the feature level;. 1. Build a proper framework. Techdocs is part of backstage and uses your own git repository to build it in markdown. https://backstage.io/docs/features/techdocs/techdocs-overview https://backstage.io/docs/features/techdocs/techdocs-overvie... has more information. Diataxis is a good start to how to think about the types of documentation. https://diataxis.fr/ https://diataxis.fr/ is what I use to separate out the types of documentation that need to be written. Most documentation in my experience is written as "explanation." Having API reference and howtos are important, and so many howtos are just built out of asking someone on slack anyway. It is a matter of saying, "you've already done the work to discover this: just put a rough draft where I've put it to be and people can refine it as they go." 2. Build an expectation of a documentation portfolio. I write about that at https://www.ebiester.com/documentation/2020/06/02/agile-documentation-takeaways.html https://www.ebiester.com/documentation/2020/06/02/agile-docu... but it was a concept written about in Agile Documentation. Start with "these are the minimum requirements for a new project" and keep it very light. Build documentation, codebase expectations, and a quick architectural tour is likely enough to start and the rest will follow. 3. Build it into the definition of done. This takes management buyin, but it means taking it into account for the schedule as technical debt originally. It will not slow you down in the end, but the activation energy of learning takes some time. But just like unit tests or manual testing, there's a set of expectations that are baked into calling something done. I think a bonus is that so much of documentation is built through our chat and email programs, and just having the courage to copy it out and clean it up a little or take videos and transcripts of debugging sessions is a good start, but it's easy to make a mess. The key is categorization.

compacct27 4y ago
Wow, I’m glad I asked. Thanks a ton, looking forward to the blog post!
- ebiester 4y ago
  https://www.ebiester.com/documentation/2022/12/23/building-documentation-culture.html https://www.ebiester.com/documentation/2022/12/23/building-d... is my thoughts. Let me know if that answers the question.