4 ms·

We used Backstage at a previous company. I was fairly unimpressed- it feels like any knowledge/documentation tool in use at a company where it only works with a

We used Backstage at a previous company. I was fairly unimpressed- it feels like any knowledge/documentation tool in use at a company where it only works with a lot of discipline to keep it up to date. Curious if others have had better experiences with this

ghaff 4y ago
Not Backstage specifically but I think you're describing documentation generally in a company of any size. Some tools are better (e.g. better search) than others. But documentation is something that's (hopefully mostly) correct the day it's created and tends to get less correct over time and may or may not get updated or formally deprecated. There needs to be a process and probably at least a librarian and even then it's often not obvious. In my experience, a lot of written material gets into the "not quite right any longer but we don't have anything better"--and if you go to update it there's invariably a lot of things that end up getting changed. Not sure I've ever cracked open an old paper or blog post and just changed one thing.
- vxNsr 4y ago
  Yup, in any midsized+ org you need a librarian if you want your doc/kb to be kept in good shape, that person also needs to have a lot of soft power/people skills to enforce rules and procedures many might feel are secondary to their main responsibilities.
- BrandoElFollito 4y ago
  I had an idea some years ago to gradually lower the contrast on the doc page until the users get frustrated and raise concerns/tickets/escalations. bringing it to a normal contrast again requires a review of the documentation and some kind of punishing if someone just clicks "yeah, it is still fine". I hate outdated documentation, primarily including mine.
  - mgkimsal 4y ago
    Not sure you'd necessarily need to rely on contrast (or... contrast alone - reader mode and similar might render that not noticeable for folks). Some datestamp next to multiple areas with a "last reviewed/approved on" info would likely be useful, esp if someone could flag items that are known out of date/wrong/broken for review, even if they didn't know what 'correct' was. I've hit this multiple times as a new person on a team/project - at least those that had moderate documentation. I know "example A" doesn't work, but I don't yet know why it's wrong or how to fix it, but flagging it for review would help me not lose track of it.
    - yjftsjthsd-h 4y ago
      I have seen personal blogs where any post that's older than some threshold automatically gets a banner tacked on the top that says something to the effect of "hey, this is an old post, things might have changed since then". Adding something like that to a Wiki seems like a reasonable idea.
      - mgkimsal 4y ago
        Going further, having someone - a librarian role - review entries that are > X months/years old seems useful. So useful that I bet it's probably something people who are 'librarians' in a tech/doc sense probably do. I've just not been in orgs large enough to have people dedicated to that role. And... on day 1, it doesn't seem necessary. I was at a small startup in their year 5, and was initially impressed with all their internal docs, until about a month in I realized huge portions were vastly out of date, sometimes even just a few months after having been written. They were growing so fast "there's no time to keep it up to date!" but I was also often told "just go find X in the docs", yet... if I followed that info, it was wrong. So I had to find the docs and about 80% of the time, schedule a meeting with the author to confirm the docs were, indeed, still "correct". Moderate waste of time, but... "there's no time to keep it updated".
    - BrandoElFollito 4y ago
      > Not sure you'd necessarily need to rely on contrast This was just an (extreme) example - what I meant is a way to make the users of the documentation pissed off enough so that they react, which in turn forces the author of the doc to update it.
- joshspankit 4y ago
  My favourite documentation setup was when we decided to go “documentation first” . The entire team would use the documentation every time, and have permissions to modify as they went. We rewarded the “extra time” needed to open the doc and follow/update process every time. (in reality the ROI makes this an easy choice). There were even cases of printing off doc pages, writing on them while in the field, and updating the digital version. And it meant that we operated with “one brain” where the documentation always represented the most current collective knowledge. It was awesomely effective
dugmartin 4y ago
I think having the documentation close to the code it documents does make sense though - otherwise it quickly gets disconnected. You just need to create a culture where approval of any code change should also include change to the documentation in the same set of commits.
nailer 4y ago
Same here. We had a wiki, only 20% of us maintained the wiki, a manager (a great cloud engineer, but less talented as a strategist) added Backstage, they were the only person that maintained Backstage,
- jsdwarf 4y ago
  Doesn't backstage offer auto-discovery of docs, ie create docs folder in repo, throw in some markdown files and everything gets picked up? If so, what kind of maintenance was required?
  - nailer 4y ago
    > Create docs folder in repo That part. Typed, properly named code doesn't need 'docs' per se. Documented code like: // Sender public key const spk; // Send tokens function txV(){ .. } Is garbage, and should be replaced with: const sender: PublicKey function sendTokens(){ .. } Code docs themselves are for things like edge cases and complexities, and URLs to bigger explanations. Those were being maintained in the wiki.
KptMarchewa 4y ago
I think Backstage is better than most tools since it integrates a lot of the functionality in one place. If you have the docs, service map, team data etc in 10 different places it will get worse.
trynewideas 4y ago
To a developer, it's unimpressive. To a technical writer with no engineering resources or experience to build their own automation who's used to static site generation or fucking DITA XML, it probably looks like magic, especially the discovery and search parts.
ebiester 4y ago
That's true no matter what. That's the manager's job to enforce the definition of done to include updating documentation, pushing to retire or archive outdated information, and providing a vision and culture of effective documentation. It's not always perfect, but there are tradeoffs in everything. My last place did a fantastic job in documentation. The culture was established before I was there, and I did bring in the diataxis framework to focus the types of documentation we wrote, but engineers had a good set of documentation to start. It wasn't all rainbows, but many slack conversations were "I wrote this a few months back - let me know what questions you have."
- compacct27 4y ago
  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.
intrasight 4y ago
Good interviewee questions: What's your ratio of technical writers to software engineers? Are their salaries equivalent? At the best companies that I've worked for, the ration was in the 1-10 to 1-5 range, and the salaries were close.
- dalyons 4y ago
  I’ve worked small and midsize startups for a decade+ and the ratio has always been 1/infinity, ie there are zero dedicated writers :/. How common is what you are advocating for? I guess I find it hard to believe 1/5 or even 1/10 companies exist. (Note: I’m not at all saying that’s a good thing )
  - intrasight 4y ago
    I've only worked at established companies. My experience was probably exceptional. At my first job, there were 30 SWEs and 4 technical writers. Boy, did that make a difference - both for our customers and for us engineers.

ghaff 4y ago

Not Backstage specifically but I think you're describing documentation generally in a company of any size. Some tools are better (e.g. better search) than others. But documentation is something that's (hopefully mostly) correct the day it's created and tends to get less correct over time and may or may not get updated or formally deprecated. There needs to be a process and probably at least a librarian and even then it's often not obvious. In my experience, a lot of written material gets into the "not quite right any longer but we don't have anything better"--and if you go to update it there's invariably a lot of things that end up getting changed. Not sure I've ever cracked open an old paper or blog post and just changed one thing.

vxNsr 4y ago
Yup, in any midsized+ org you need a librarian if you want your doc/kb to be kept in good shape, that person also needs to have a lot of soft power/people skills to enforce rules and procedures many might feel are secondary to their main responsibilities.
BrandoElFollito 4y ago
I had an idea some years ago to gradually lower the contrast on the doc page until the users get frustrated and raise concerns/tickets/escalations. bringing it to a normal contrast again requires a review of the documentation and some kind of punishing if someone just clicks "yeah, it is still fine". I hate outdated documentation, primarily including mine.
- mgkimsal 4y ago
  Not sure you'd necessarily need to rely on contrast (or... contrast alone - reader mode and similar might render that not noticeable for folks). Some datestamp next to multiple areas with a "last reviewed/approved on" info would likely be useful, esp if someone could flag items that are known out of date/wrong/broken for review, even if they didn't know what 'correct' was. I've hit this multiple times as a new person on a team/project - at least those that had moderate documentation. I know "example A" doesn't work, but I don't yet know why it's wrong or how to fix it, but flagging it for review would help me not lose track of it.
  - yjftsjthsd-h 4y ago
    I have seen personal blogs where any post that's older than some threshold automatically gets a banner tacked on the top that says something to the effect of "hey, this is an old post, things might have changed since then". Adding something like that to a Wiki seems like a reasonable idea.
    - mgkimsal 4y ago
      Going further, having someone - a librarian role - review entries that are > X months/years old seems useful. So useful that I bet it's probably something people who are 'librarians' in a tech/doc sense probably do. I've just not been in orgs large enough to have people dedicated to that role. And... on day 1, it doesn't seem necessary. I was at a small startup in their year 5, and was initially impressed with all their internal docs, until about a month in I realized huge portions were vastly out of date, sometimes even just a few months after having been written. They were growing so fast "there's no time to keep it up to date!" but I was also often told "just go find X in the docs", yet... if I followed that info, it was wrong. So I had to find the docs and about 80% of the time, schedule a meeting with the author to confirm the docs were, indeed, still "correct". Moderate waste of time, but... "there's no time to keep it updated".
  - BrandoElFollito 4y ago
    > Not sure you'd necessarily need to rely on contrast This was just an (extreme) example - what I meant is a way to make the users of the documentation pissed off enough so that they react, which in turn forces the author of the doc to update it.
joshspankit 4y ago
My favourite documentation setup was when we decided to go “documentation first” . The entire team would use the documentation every time, and have permissions to modify as they went. We rewarded the “extra time” needed to open the doc and follow/update process every time. (in reality the ROI makes this an easy choice). There were even cases of printing off doc pages, writing on them while in the field, and updating the digital version. And it meant that we operated with “one brain” where the documentation always represented the most current collective knowledge. It was awesomely effective

dugmartin 4y ago

I think having the documentation close to the code it documents does make sense though - otherwise it quickly gets disconnected. You just need to create a culture where approval of any code change should also include change to the documentation in the same set of commits.

nailer 4y ago

Same here. We had a wiki, only 20% of us maintained the wiki, a manager (a great cloud engineer, but less talented as a strategist) added Backstage, they were the only person that maintained Backstage,

jsdwarf 4y ago
Doesn't backstage offer auto-discovery of docs, ie create docs folder in repo, throw in some markdown files and everything gets picked up? If so, what kind of maintenance was required?
- nailer 4y ago
  > Create docs folder in repo That part. Typed, properly named code doesn't need 'docs' per se. Documented code like: // Sender public key const spk; // Send tokens function txV(){ .. } Is garbage, and should be replaced with: const sender: PublicKey function sendTokens(){ .. } Code docs themselves are for things like edge cases and complexities, and URLs to bigger explanations. Those were being maintained in the wiki.

KptMarchewa 4y ago

I think Backstage is better than most tools since it integrates a lot of the functionality in one place. If you have the docs, service map, team data etc in 10 different places it will get worse.

trynewideas 4y ago

To a developer, it's unimpressive. To a technical writer with no engineering resources or experience to build their own automation who's used to static site generation or fucking DITA XML, it probably looks like magic, especially the discovery and search parts.

ebiester 4y ago

That's true no matter what. That's the manager's job to enforce the definition of done to include updating documentation, pushing to retire or archive outdated information, and providing a vision and culture of effective documentation. It's not always perfect, but there are tradeoffs in everything. My last place did a fantastic job in documentation. The culture was established before I was there, and I did bring in the diataxis framework to focus the types of documentation we wrote, but engineers had a good set of documentation to start. It wasn't all rainbows, but many slack conversations were "I wrote this a few months back - let me know what questions you have."

compacct27 4y ago
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.

intrasight 4y ago

Good interviewee questions: What's your ratio of technical writers to software engineers? Are their salaries equivalent? At the best companies that I've worked for, the ration was in the 1-10 to 1-5 range, and the salaries were close.

dalyons 4y ago
I’ve worked small and midsize startups for a decade+ and the ratio has always been 1/infinity, ie there are zero dedicated writers :/. How common is what you are advocating for? I guess I find it hard to believe 1/5 or even 1/10 companies exist. (Note: I’m not at all saying that’s a good thing )
- intrasight 4y ago
  I've only worked at established companies. My experience was probably exceptional. At my first job, there were 30 SWEs and 4 technical writers. Boy, did that make a difference - both for our customers and for us engineers.