3 ms·

I find these solutions actually make documentation harder. They're binary and proprietary in nature, locked behind a paywall if I can no longer afford the servi

by movedx 4y ago

I find these solutions actually make documentation harder. They're binary and proprietary in nature, locked behind a paywall if I can no longer afford the service (and what's the exportable data going to look like? XML?), And the UI is often limited and leaves a lot to be desired. My code is not binary, however, it's plain text. So I write my documentation in plain text too, such as Markdown. That can, should I so choose, be rendered to anything I like. It can be included alongside the code, which the developer will need a copy of anyway, and be easily reviewed (with "mkdocs serve" for example). You're already committing code to a central repository and working in a decentralised manner. If you put your documentation in "./docs/" (I recommend MkDocs + the Material Theme) and commit it, then everyone has access to it immediately. It's free, close to the code and in context, everyone who needs access to it has it, and it's simple to use. It's also local, extremely fast and, if desired, can be easily embedded into a CI pipeline, compiled to anything you like (Markdown => *) and pushed to wherever you like. I also don't understand the obsession with making documentation available online, 24/7, when we live in a cyber security nightmare right now (https://www.hertzbleed.com/ https://www.hertzbleed.com/; https://securityboulevard.com/2022/06/apple-m1-flaw-cant-be-fixed-pacman-panic/ https://securityboulevard.com/2022/06/apple-m1-flaw-cant-be-...; https://www.darkreading.com/threat-intelligence/emotet-banking-trojan-resurfaces-email-security https://www.darkreading.com/threat-intelligence/emotet-banki...; https://www.darkreading.com/edge-articles/turbulent-cyber-insurance-market-sees-rising-prices-and-sinking-coverage https://www.darkreading.com/edge-articles/turbulent-cyber-in....) Just keep it within context, plain text, and easily convertible to other formats. Try not to over think things.

hanyiwang 4y ago
We totally agree! We think it would be best when documentation is centralized, version controlled, and coupled with the code. Unfortunately, we realized that's just not the case for the vast majority of companies. One way to think about our product is just bringing the features of documentation on GitHub into existing documentation that lives outside of it.
- movedx 4y ago
  A potentially valueable goal. I wish you luck. > Unfortunately, we realized that's just not the case for the vast majority of companies. Nor is DevOps, but that's changing. And as more things shift-left and get actioned in a CI/CD pipeline, companies are going to want more automation, checks, analysis, etc., of all their digital assets. That includes documentation - spell checks, auto-generated and static, checking for broken links, warnings about docs that haven't been reviewed or updated for X days, and more. That's the real answer to this problem: how do we keep documentation close to the context to which it relates, AND allow it to be manipulated, tested, and more, all through automated business logic? Solve that.
  - hahnbee 4y ago
    > how do we keep documentation close to the context to which it relates, AND allow it to be manipulated, tested, and more, all through automated business logic? Solve that. Well spoken.

by movedx 4y ago

hanyiwang 4y ago

We totally agree! We think it would be best when documentation is centralized, version controlled, and coupled with the code. Unfortunately, we realized that's just not the case for the vast majority of companies. One way to think about our product is just bringing the features of documentation on GitHub into existing documentation that lives outside of it.

movedx 4y ago
A potentially valueable goal. I wish you luck. > Unfortunately, we realized that's just not the case for the vast majority of companies. Nor is DevOps, but that's changing. And as more things shift-left and get actioned in a CI/CD pipeline, companies are going to want more automation, checks, analysis, etc., of all their digital assets. That includes documentation - spell checks, auto-generated and static, checking for broken links, warnings about docs that haven't been reviewed or updated for X days, and more. That's the real answer to this problem: how do we keep documentation close to the context to which it relates, AND allow it to be manipulated, tested, and more, all through automated business logic? Solve that.
- hahnbee 4y ago
  > how do we keep documentation close to the context to which it relates, AND allow it to be manipulated, tested, and more, all through automated business logic? Solve that. Well spoken.