5 ms·

Hi I've been a technical writer for ~9 years: 3 at a startup and 6 at Google. I agree that documentation maintenance is probably the real hard problem. I think

Hi I've been a technical writer for ~9 years: 3 at a startup and 6 at Google. I agree that documentation maintenance is probably the real hard problem. I think the winner of this space will be the one who solves the "connect code to documentation" aspect most effectively. Looking at your demo, I don't think the code/doc connection should be invisible metadata. In other words my hunch is that the code/doc connection needs to be obvious in code/doc themselves although I'm not sure why I feel this way at the moment. Also the root causes of stale documentation are usually a combination of 1) documentation not being incentivized by org leadership 2) the gradual but persistent proliferation of docs. I don't mean to say that these are people problems that are not solvable by technology. I do think they are solvable by technology but you'll need to get very creative and innovative to solve them. E.g. to address #1 maybe some kind of reporting system that makes leadership aware of which engineers are doing docs work that is truly creating value for the org. Happy to chat 1:1 and thank you for bringing innovations to my industry!

hanyiwang 4y ago
Thank you so much for the incredible feedback! We think you are absolutely SPOT ON. We would really love to chat more with you 1:1. Please reach out to us at han@mintlify.com
dllthomas 4y ago
I've taken to supporting cross-references across the repo, connecting references of the form ^^{foo} to anchors of the form @@{foo}, wherever they appear (code, comment, docs). Then I have CI check referential integrity and also surface connections in code review (adding annotations to all references when the corresponding anchor shows up in the diff in changed lines or context, and vice-versa). In the idealized straight-forward elaboration, then, all docs would live in the repo, but I haven't worked with a team that was on board with that. I'd also like to see a better tie between docs and tests.
- hahnbee 4y ago
  That's very interesting. How did you implement this? : "I've taken to supporting cross-references across the repo, connecting references of the form ^^{foo} to anchors of the form @@{foo}, wherever they appear (code, comment, docs)." Do you have a link? Would love to check it out myself. I'm also curious - why do you think most people are against docs living inside the repo?
  - dllthomas 4y ago
    > How did you implement this? It wasn't public code, so no links handy, but the implementation was pretty much what you'd expect. For checking referential integrity, make a list of all references and a list of all referents and diff the two. Trivial with git grep and a little bash, but pick your poison. For surfacing connections, it was a matter of finding them in changes (which was approximately piping git diff to grep) , finding the corresponding locations in the whole repo, and then adding those locations to the PR, for which I used the github Checks API (you can add annotations in the output of a Check Run, see https://docs.github.com/en/rest/checks/runs#create-a-check-run https://docs.github.com/en/rest/checks/runs#create-a-check-r...). > why do you think most people are against docs living inside the repo? For internal docs, I think it's an impression that Notion or Google Docs or Confluence or whatever is "easier", although it's usually been easier to get some measure of buy-in for at least some set of internal docs. For external docs, it's "of course we can't teach git to anyone but engineers!" Which hasn't tracked my limited experience in trying to do so, but it can be hard to get them to try to learn in the first place.
    - hahnbee 4y ago
      Gotcha, apologies for all the questions - did you implement this for your company? That's interesting that the reception you got was primarily against documentation inside a repo. Maybe Gitbook could've been a good compromise? I recently made this post on reddit https://www.reddit.com/r/devops/comments/v6yuu5/whats_your_documentation_stack/ https://www.reddit.com/r/devops/comments/v6yuu5/whats_your_d... and many of the comments prefer to have documentation in the repo.
      - 4y ago
- kaycebasques 4y ago
  > In the idealized straight-forward elaboration, then, all docs would live in the repo, but I haven't worked with a team that was on board with that In case you're thinking about productizing your work I just want to give you a little encouragement that there are a lot of companies OK with having docs live alongside code. See Google's g3doc [1] for example. See also the docs as code movement. [1] https://www.usenix.org/conference/srecon16europe/program/presentation/macnamara https://www.usenix.org/conference/srecon16europe/program/pre...
  - hanyiwang 4y ago
    Thank you for sharing the article! We definitely don't see companies having all docs in their repos, but strongly believe that there should be stronger ties between docs and code (and more transparency in docs in general) It's a really hard problem to solve, but we believe that there will be a product that will crack it (even if it's not what we have right now)
  - dllthomas 4y ago
    Thanks! At the moment it feels much too small to productize; virtually all of the complexity is the CI integration, and even that is small.
infogulch 4y ago
What do you think about documentation organization methodologies? And this one in particular: https://documentation.divio.com/ https://documentation.divio.com/
- kaycebasques 4y ago
  Love the Divio docs system. AKA https://diataxis.fr https://diataxis.fr now. I regularly mention it when explaining basic docs strategy to stakeholders. Pretty much all professional technical writers subscribe to an organization methodology like this, they just may not use the Divio/Diataxis name. Also Divio/Diataxis did not invent this idea: they just did the best job explaining it.
  - infogulch 4y ago
    Thanks for your input!
quickthrower2 4y ago
I agree you need incentives for people to write documentation. Part of documentation is keeping it up to date (as shown in the demo video, keeping code in sync) but another important part is providing a way for newcomers to learn. Reference documentation is different to teaching documentation. Maybe a good platform can encourage this.
- jeffreygoesto 4y ago
  I can confirm the last point and want to support that with a taxonomy and talk that helped us a lot: https://documentation.divio.com/ https://documentation.divio.com/
- hanyiwang 4y ago
  Excellent suggestion. We're gonna work this into the product for sure
jeffreygoesto 4y ago
Maybe job rotation and showing people the difference between good and bad documents when they are on the receiving end helps?. My theory is that part of the problem is that effort and benefit are split across roles and the people thst should spend the effort never perceive that they get enough benefit back?
pixel_tracing 4y ago
I agree with your sentiments have you looked at how Apple has integrated Doc-C with Xcode?

hanyiwang 4y ago

Thank you so much for the incredible feedback! We think you are absolutely SPOT ON. We would really love to chat more with you 1:1. Please reach out to us at han@mintlify.com

dllthomas 4y ago

I've taken to supporting cross-references across the repo, connecting references of the form ^^{foo} to anchors of the form @@{foo}, wherever they appear (code, comment, docs). Then I have CI check referential integrity and also surface connections in code review (adding annotations to all references when the corresponding anchor shows up in the diff in changed lines or context, and vice-versa). In the idealized straight-forward elaboration, then, all docs would live in the repo, but I haven't worked with a team that was on board with that. I'd also like to see a better tie between docs and tests.

hahnbee 4y ago
That's very interesting. How did you implement this? : "I've taken to supporting cross-references across the repo, connecting references of the form ^^{foo} to anchors of the form @@{foo}, wherever they appear (code, comment, docs)." Do you have a link? Would love to check it out myself. I'm also curious - why do you think most people are against docs living inside the repo?
- dllthomas 4y ago
  > How did you implement this? It wasn't public code, so no links handy, but the implementation was pretty much what you'd expect. For checking referential integrity, make a list of all references and a list of all referents and diff the two. Trivial with git grep and a little bash, but pick your poison. For surfacing connections, it was a matter of finding them in changes (which was approximately piping git diff to grep) , finding the corresponding locations in the whole repo, and then adding those locations to the PR, for which I used the github Checks API (you can add annotations in the output of a Check Run, see https://docs.github.com/en/rest/checks/runs#create-a-check-run https://docs.github.com/en/rest/checks/runs#create-a-check-r...). > why do you think most people are against docs living inside the repo? For internal docs, I think it's an impression that Notion or Google Docs or Confluence or whatever is "easier", although it's usually been easier to get some measure of buy-in for at least some set of internal docs. For external docs, it's "of course we can't teach git to anyone but engineers!" Which hasn't tracked my limited experience in trying to do so, but it can be hard to get them to try to learn in the first place.
  - hahnbee 4y ago
    Gotcha, apologies for all the questions - did you implement this for your company? That's interesting that the reception you got was primarily against documentation inside a repo. Maybe Gitbook could've been a good compromise? I recently made this post on reddit https://www.reddit.com/r/devops/comments/v6yuu5/whats_your_documentation_stack/ https://www.reddit.com/r/devops/comments/v6yuu5/whats_your_d... and many of the comments prefer to have documentation in the repo.
    - 4y ago
kaycebasques 4y ago
> In the idealized straight-forward elaboration, then, all docs would live in the repo, but I haven't worked with a team that was on board with that In case you're thinking about productizing your work I just want to give you a little encouragement that there are a lot of companies OK with having docs live alongside code. See Google's g3doc [1] for example. See also the docs as code movement. [1] https://www.usenix.org/conference/srecon16europe/program/presentation/macnamara https://www.usenix.org/conference/srecon16europe/program/pre...
- hanyiwang 4y ago
  Thank you for sharing the article! We definitely don't see companies having all docs in their repos, but strongly believe that there should be stronger ties between docs and code (and more transparency in docs in general) It's a really hard problem to solve, but we believe that there will be a product that will crack it (even if it's not what we have right now)
- dllthomas 4y ago
  Thanks! At the moment it feels much too small to productize; virtually all of the complexity is the CI integration, and even that is small.

infogulch 4y ago

What do you think about documentation organization methodologies? And this one in particular: https://documentation.divio.com/ https://documentation.divio.com/

kaycebasques 4y ago
Love the Divio docs system. AKA https://diataxis.fr https://diataxis.fr now. I regularly mention it when explaining basic docs strategy to stakeholders. Pretty much all professional technical writers subscribe to an organization methodology like this, they just may not use the Divio/Diataxis name. Also Divio/Diataxis did not invent this idea: they just did the best job explaining it.
- infogulch 4y ago
  Thanks for your input!

quickthrower2 4y ago

I agree you need incentives for people to write documentation. Part of documentation is keeping it up to date (as shown in the demo video, keeping code in sync) but another important part is providing a way for newcomers to learn. Reference documentation is different to teaching documentation. Maybe a good platform can encourage this.

jeffreygoesto 4y ago
I can confirm the last point and want to support that with a taxonomy and talk that helped us a lot: https://documentation.divio.com/ https://documentation.divio.com/
hanyiwang 4y ago
Excellent suggestion. We're gonna work this into the product for sure

jeffreygoesto 4y ago

Maybe job rotation and showing people the difference between good and bad documents when they are on the receiving end helps?. My theory is that part of the problem is that effort and benefit are split across roles and the people thst should spend the effort never perceive that they get enough benefit back?

pixel_tracing 4y ago

I agree with your sentiments have you looked at how Apple has integrated Doc-C with Xcode?