5 ms·

This is too biased for-docs IMHO*. I do agree with many points, documentation IS amazing, and you are very likely under-documenting things in your company. But

This is too biased for-docs IMHO*. I do agree with many points, documentation IS amazing, and you are very likely under-documenting things in your company. But documentation is not cheap to create, and specially it's not cheap to maintain. If you are not writing enough yes, sure, that's probably a great investment, but start bit by bit. I've worked in multiple* companies where the problem was too much documentation, and of course everyone was afraid to update or ghasps* remove any piece of old documentation in case it was still useful. Imagine working on a codebase where 80% of the code was unused or commented out but no one dared changing it just in case (flashback to 2010 with 4000 lines of style.css). I'd suggest to take a more holistic approach and treat documentation a lot like testing; for that prototype, probably just write the barebones documentation, for the production-ready new feature go all-in and write detailed documentation, tutorials, etc. If you do want to go deeper with documentation, then you'll need a dedicated team (like a team of testers) that work exclusively on documentation. At some point it does make sense to hire only for that, and it can even be a differentiating point for your startup if done correctly. For libraries, a ratio I've seen works pretty well is approx 1:3:5 for lines of code:tests:docs; you can do tests first, or even documentation first, but once everything is finished and if you count the amount of lines that's a decent ratio. Note that when counting "lines of docs" in an editor, a whole paragraph will count as just 1, so in reality there's a lot more docs. Note: I'm the creator of both https://documentation.page/ https://documentation.page/ and https://documentation.agency/ https://documentation.agency/ * (only 2 "negative" paragraphs on a book-length article)

atoav 3y ago
I really like the way documentation works in Rust: You basically write markdown in a special type of comment over the module, function, datatype or method you wanna document and then you can convert that into documentation automatically. Even better: if you have examples in code blocks in these docstrings per default they get tested as well, so if you don't update them, the tests will fail and you will notice. In my eyes one of the biggest problems with keeping documentation up to date is that over time the mapping between the piece of code you are documenting and the place where you find it in the documentation becomes more complex, to a point where missing something is not unlikely. Rust's documentation-in-code-approach addresses this problem neatly.
- cjfd 3y ago
  I don't have experience with this in Rust but have come to passionately hate this kind of documentation in other language. I think all of pydoc, javadoc and, doxygen are all garbage. If one could apply them sensibly it would not be so much of a problem but then you have documentation nazis who force you to document every method and every parameter. This leads to hightly enlightening prose documentation that the get_height method "gets the height", and that its return value is the height. A more high level problem with this is that you get documentation that is just as fragmented as the code and where the high level usage of things is not explained at all. Also it clutters the code with many highly trivial remarks.
  - Karrot_Kream 3y ago
    Yeah this is why I love literate programming. Being able to read a program with "narration" is so much nicer than just reading documentation piecemeal. Maintaining literate programs though is a quite difficult because you have to figure out where new code or changes fit in the overall narrative. I have a scraper I wrote in literate style and I only have to change it yearly. Each year I forget what I wrote and then I reread the program and make the necessary changes.
    - bayindirh 3y ago
      Literate programming is great until your code base becomes unwieldy. Then you need a README.md file which acts like a pointer to the correct entry points. Then as the code grows, you need to document the architecture, add small gotchas, etc. At the end of the day, documentation wins.
    - atoav 3y ago
      I am very code literate, but depending on the size of the codebase and how much smoke and mirrors are used, I might take longer to grok how things are interconnected by reading the code than it would take me if someone gave an high level overview in a paragraph or two.
  - c00lio 3y ago
johnnyanmac 3y ago
>I've worked in multiple* companies where the problem was too much documentation, and of course everyone was afraid to update or ghasps* That must be nice. I've yet to work on a company where half my time wasn't trying to prod for some resource (be it internal code, a public 3rd party tool, or even the resource itself), sometimes playing a game of goose just to figure out who knows the author. I'd love too much documentation. But I understand your point. The only thing worse than no documentation is wrong documentation, and outdated docs half the time can become outright wrong half the time, if it isn't simply encouraging outdated but functional practices. Tech writers are highly undervalued for that purpose. I should also mention that the ability to properly search for docs is almost more important than the doc itself. Some companies had wikis but good luck searching for the right keywords if you didn't know the exact title. A properly categorized top level page could have helped a lot (and is probably easier/cheaper than integrating google like searchabilty into an internal database).
- franciscop 3y ago
  > That must be nice > The only thing worse than no documentation is wrong documentation Yeah, that was the exact problem. One was a startup and when I joined it was all mostly up-to-date so it was great! But by the time I left (after 2 major migrations) most of it was out of date and a nightmare to find anything updated, any script that could still be run, etc.
hahnbee 3y ago
I'm the CTO of Mintlify - we help other startups create their developer-facing documentation. We've been working in the documentation space for a little over a year now and I spend a lot of time thinking about documentation. I completely agree here. Documentation is such a hard problem to "solve" if you're a fast-moving startup. You need a mixture of creating a documentation-first culture and acknowledging that documentation is difficult to maintain. Ultimately you end up creating processes to help people document their intent, decisions and the mission critical information. There is also such a large range of types of documentation - varying scale from internal to external and technical to non-technical. We started by creating https://writer.mintlify.com/ https://writer.mintlify.com/ which really resonated with developers because it made it easier to write documentation, but it only helped generate documentation that was highly technical and close to the code. We decided to stay in the documentation space but try another vector and so now we're taking a crack at public-facing documentation - which in my opinion is a different can of worms than internal documentation. However as I'm building and growing my startup and I find myself continuously playing whack-a-mole and I definitely hope that we can build the foundation and expand to make it easier to maintain all different types of documentation.
- kristiandupont 3y ago
  I'm trying your extension out and it looks promising. A tiny bit of feedback: the shortcut key is defined in settings, not keybindings which seems wrong? Also, the default is to override cmd+. which is an important shortcut already..
CharlieDigital 3y ago
> Imagine working on a codebase where 80% of the code was unused or commented out That's not documentation; that's code.
- phkahler 3y ago
  >> That's not documentation; that's code. It's an analogy to make the point - we delete old code that's not relevant any more. Imagine reading documentation where 80 percent of it is no longer relevant but is kept around "just in case".
  - deleted 3y ago
    [deleted]

atoav 3y ago

I really like the way documentation works in Rust: You basically write markdown in a special type of comment over the module, function, datatype or method you wanna document and then you can convert that into documentation automatically. Even better: if you have examples in code blocks in these docstrings per default they get tested as well, so if you don't update them, the tests will fail and you will notice. In my eyes one of the biggest problems with keeping documentation up to date is that over time the mapping between the piece of code you are documenting and the place where you find it in the documentation becomes more complex, to a point where missing something is not unlikely. Rust's documentation-in-code-approach addresses this problem neatly.

cjfd 3y ago
I don't have experience with this in Rust but have come to passionately hate this kind of documentation in other language. I think all of pydoc, javadoc and, doxygen are all garbage. If one could apply them sensibly it would not be so much of a problem but then you have documentation nazis who force you to document every method and every parameter. This leads to hightly enlightening prose documentation that the get_height method "gets the height", and that its return value is the height. A more high level problem with this is that you get documentation that is just as fragmented as the code and where the high level usage of things is not explained at all. Also it clutters the code with many highly trivial remarks.
- Karrot_Kream 3y ago
  Yeah this is why I love literate programming. Being able to read a program with "narration" is so much nicer than just reading documentation piecemeal. Maintaining literate programs though is a quite difficult because you have to figure out where new code or changes fit in the overall narrative. I have a scraper I wrote in literate style and I only have to change it yearly. Each year I forget what I wrote and then I reread the program and make the necessary changes.
  - bayindirh 3y ago
    Literate programming is great until your code base becomes unwieldy. Then you need a README.md file which acts like a pointer to the correct entry points. Then as the code grows, you need to document the architecture, add small gotchas, etc. At the end of the day, documentation wins.
  - atoav 3y ago
    I am very code literate, but depending on the size of the codebase and how much smoke and mirrors are used, I might take longer to grok how things are interconnected by reading the code than it would take me if someone gave an high level overview in a paragraph or two.
- c00lio 3y ago

johnnyanmac 3y ago

>I've worked in multiple* companies where the problem was too much documentation, and of course everyone was afraid to update or ghasps* That must be nice. I've yet to work on a company where half my time wasn't trying to prod for some resource (be it internal code, a public 3rd party tool, or even the resource itself), sometimes playing a game of goose just to figure out who knows the author. I'd love too much documentation. But I understand your point. The only thing worse than no documentation is wrong documentation, and outdated docs half the time can become outright wrong half the time, if it isn't simply encouraging outdated but functional practices. Tech writers are highly undervalued for that purpose. I should also mention that the ability to properly search for docs is almost more important than the doc itself. Some companies had wikis but good luck searching for the right keywords if you didn't know the exact title. A properly categorized top level page could have helped a lot (and is probably easier/cheaper than integrating google like searchabilty into an internal database).

franciscop 3y ago
> That must be nice > The only thing worse than no documentation is wrong documentation Yeah, that was the exact problem. One was a startup and when I joined it was all mostly up-to-date so it was great! But by the time I left (after 2 major migrations) most of it was out of date and a nightmare to find anything updated, any script that could still be run, etc.

hahnbee 3y ago

I'm the CTO of Mintlify - we help other startups create their developer-facing documentation. We've been working in the documentation space for a little over a year now and I spend a lot of time thinking about documentation. I completely agree here. Documentation is such a hard problem to "solve" if you're a fast-moving startup. You need a mixture of creating a documentation-first culture and acknowledging that documentation is difficult to maintain. Ultimately you end up creating processes to help people document their intent, decisions and the mission critical information. There is also such a large range of types of documentation - varying scale from internal to external and technical to non-technical. We started by creating https://writer.mintlify.com/ https://writer.mintlify.com/ which really resonated with developers because it made it easier to write documentation, but it only helped generate documentation that was highly technical and close to the code. We decided to stay in the documentation space but try another vector and so now we're taking a crack at public-facing documentation - which in my opinion is a different can of worms than internal documentation. However as I'm building and growing my startup and I find myself continuously playing whack-a-mole and I definitely hope that we can build the foundation and expand to make it easier to maintain all different types of documentation.

kristiandupont 3y ago
I'm trying your extension out and it looks promising. A tiny bit of feedback: the shortcut key is defined in settings, not keybindings which seems wrong? Also, the default is to override cmd+. which is an important shortcut already..

CharlieDigital 3y ago

> Imagine working on a codebase where 80% of the code was unused or commented out That's not documentation; that's code.

phkahler 3y ago
>> That's not documentation; that's code. It's an analogy to make the point - we delete old code that's not relevant any more. Imagine reading documentation where 80 percent of it is no longer relevant but is kept around "just in case".
- deleted 3y ago
  [deleted]