4 ms·

There is a cost to writing documentation - it takes time, which could be used to improve Zig in other areas. For code that is work-in-progress, it can make sens

There is a cost to writing documentation - it takes time, which could be used to improve Zig in other areas. For code that is work-in-progress, it can make sense to not document until things are more settled. Of course documentation is good. But if you have to prioritize either a new feature, or a critical bugfix, or documentation, you often can't have it all

wordofx 1y ago
Na. It’s flat out laziness. Don’t make excuses. Either write docs or stop worrying code.
hardwaresofton 1y ago
This is a good point, but one could make a point for the usefulness of documentation in “thinking like a user” which is a valuable exercise. I do very much prefer moving fast though, so I get it, docs-later is obviously a very valid way of doing things. If someone is excited about Zig and wanted to make a difference I guess it’s now obvious where they could have outsized impact!
- 7bit 1y ago
  Docs later is an okay approach, when you build something in a closed environment, where the only users know the code inside out. But when working in open-source and your goal is to have people adopt your software, then it's a bad point and a lazy excuse.
HeartofCPU 1y ago
Very good point
aDyslecticCrow 1y ago
Then they should not have relead the new api at all. Why release half finnished library.
- flohofwoe 1y ago
  Zig as a whole is half-finished, should it be kept under wraps until it is ready? There's a reason for the 0.x version number, if you can't live with breaking changes, don't use Zig yet. It's as simple as that.
  - aDyslecticCrow 1y ago
    Breaking changes and limited support is one thing. But docs is not something you add at at the end. Lacking docs and Lacking tests is code that should not be released. They target embedded c market. Limited support and features is expected and common. But being lax with docs and testing is not acceptable.
    - flohofwoe 1y ago
      > But being lax with docs and testing is not acceptable. First: Those two things are not the same. The Zig stdlib and compiler have tons of tests, and it's actually quite rare to stumble over implementation bugs. Second: I'd rather take no docs at all than per-function or per-type doc-headers which just repeat what the code does in natural language (and then may quickly get stale). Some parent wrote about generating docs with an LLM which is just a laughably bad idea, since even with perfect results you'll just get a redundant reiteration of what the code below does, just in imprecise human language, it would literally just be redundant noise. Documentation mostly makes sense up on the systems level to explain high level concepts, not as 'this function does this and that...' level, this information already exists in much more precise form in the source code below the doc header. But this sort of high level documentation doesn't make sense as long as a project is in the experimentation phase, and Zig is still one big experiment.
      - aDyslecticCrow 1y ago
        I fundamentally disagree on code readability. A comment on the function header can save an hour of code reverse engineering for a complex library. Reading code is a last resort, and stale code docs is itself a red flag. This post itself is a great example. The code is not self explanatory unless you understand the library below. So if this was library code; you would have to reverse through two abstraktion walls to understand it. And as for high level documentation... it would be very helpful to have that DURING the development process to discuss the implementation, and quickly get people up-to-speed in the plan during code review. Id write that before the code. I mention tests, because they are 10x more work to write than docs. So if the developer skips out on docs, my trust in their testing is also destroyed.
simonask 1y ago
I tend to actually disagree with this attitude, because I see writing documentation as really effective "rubber-ducking". If it's hard and time-consuming to properly document, it's probably hard to use, so extra effort should be spent to actually justify the design, not least to yourself in 6 months. If you can't justify it, it's probably wrong.
- pmarreck 1y ago
  100%. Similar to how TDD forces you to first figure out the API of your code due to the test code being its first client.
- kelnos 1y ago
  This really struck a chord with me. Writing documentation is an act of explaining something to others. Explaining something to others is a great way to test your own understanding. If it's hard to explain to someone else, then maybe it's the wrong design. If you don't through that exercise, you're much more likely to build confusing, difficult-to-use APIs.
  - throwawaymaths 1y ago
    > you're much more likely to build confusing, difficult-to-use APIs. have not found this to be the case with zig in general. you could easily make the opposite argument, that documenting things (especially quirks) can give you license to build confusing APIs.
    - ioasuncvinvaer 1y ago
      I think some documentation and a handful of examples would have helped the author of the article. How is the experience when porting to the new standard library improved by not including documentation?
    - CRConrad 1y ago
      > > you're much more likely to build confusing, difficult-to-use APIs. > have not found this to be the case with zig in general. Dunno how general it is, but TFA we're discussing here contains an example, so AFAICS it seems at least a little too common.
7bit 1y ago
Your argument implies that good documentation is not an improvement, which of course is wrong. It also belongs to the task of improving code. Why would you move away after half-assing the API, when you can add the docs and whole-ass it instead?
crote 1y ago
On the other hand, not writing documentation also has a cost. Code is rarely written from start to finish in a single session. Would you rather spend 5 minutes before you do a git commit to write down some very basic documentation, or spend an hour rediscovering it when you pick up development two weeks later? Nobody is expecting extensive and well-polished documentation here, but is a "Flags X, Y, and Z are mandatory, buffer A is required: I tested with 10MB, smaller might be fine too" really too much to ask for? Is the time you saved by not writing that one line worth someone else spending several hours figuring out how to do a "hello world"?

wordofx 1y ago

Na. It’s flat out laziness. Don’t make excuses. Either write docs or stop worrying code.

hardwaresofton 1y ago

This is a good point, but one could make a point for the usefulness of documentation in “thinking like a user” which is a valuable exercise. I do very much prefer moving fast though, so I get it, docs-later is obviously a very valid way of doing things. If someone is excited about Zig and wanted to make a difference I guess it’s now obvious where they could have outsized impact!

7bit 1y ago
Docs later is an okay approach, when you build something in a closed environment, where the only users know the code inside out. But when working in open-source and your goal is to have people adopt your software, then it's a bad point and a lazy excuse.

HeartofCPU 1y ago

Very good point

aDyslecticCrow 1y ago

Then they should not have relead the new api at all. Why release half finnished library.

flohofwoe 1y ago
Zig as a whole is half-finished, should it be kept under wraps until it is ready? There's a reason for the 0.x version number, if you can't live with breaking changes, don't use Zig yet. It's as simple as that.
- aDyslecticCrow 1y ago
  Breaking changes and limited support is one thing. But docs is not something you add at at the end. Lacking docs and Lacking tests is code that should not be released. They target embedded c market. Limited support and features is expected and common. But being lax with docs and testing is not acceptable.
  - flohofwoe 1y ago
    > But being lax with docs and testing is not acceptable. First: Those two things are not the same. The Zig stdlib and compiler have tons of tests, and it's actually quite rare to stumble over implementation bugs. Second: I'd rather take no docs at all than per-function or per-type doc-headers which just repeat what the code does in natural language (and then may quickly get stale). Some parent wrote about generating docs with an LLM which is just a laughably bad idea, since even with perfect results you'll just get a redundant reiteration of what the code below does, just in imprecise human language, it would literally just be redundant noise. Documentation mostly makes sense up on the systems level to explain high level concepts, not as 'this function does this and that...' level, this information already exists in much more precise form in the source code below the doc header. But this sort of high level documentation doesn't make sense as long as a project is in the experimentation phase, and Zig is still one big experiment.
    - aDyslecticCrow 1y ago
      I fundamentally disagree on code readability. A comment on the function header can save an hour of code reverse engineering for a complex library. Reading code is a last resort, and stale code docs is itself a red flag. This post itself is a great example. The code is not self explanatory unless you understand the library below. So if this was library code; you would have to reverse through two abstraktion walls to understand it. And as for high level documentation... it would be very helpful to have that DURING the development process to discuss the implementation, and quickly get people up-to-speed in the plan during code review. Id write that before the code. I mention tests, because they are 10x more work to write than docs. So if the developer skips out on docs, my trust in their testing is also destroyed.

simonask 1y ago

I tend to actually disagree with this attitude, because I see writing documentation as really effective "rubber-ducking". If it's hard and time-consuming to properly document, it's probably hard to use, so extra effort should be spent to actually justify the design, not least to yourself in 6 months. If you can't justify it, it's probably wrong.

pmarreck 1y ago
100%. Similar to how TDD forces you to first figure out the API of your code due to the test code being its first client.
kelnos 1y ago
This really struck a chord with me. Writing documentation is an act of explaining something to others. Explaining something to others is a great way to test your own understanding. If it's hard to explain to someone else, then maybe it's the wrong design. If you don't through that exercise, you're much more likely to build confusing, difficult-to-use APIs.
- throwawaymaths 1y ago
  > you're much more likely to build confusing, difficult-to-use APIs. have not found this to be the case with zig in general. you could easily make the opposite argument, that documenting things (especially quirks) can give you license to build confusing APIs.
  - ioasuncvinvaer 1y ago
    I think some documentation and a handful of examples would have helped the author of the article. How is the experience when porting to the new standard library improved by not including documentation?
  - CRConrad 1y ago
    > > you're much more likely to build confusing, difficult-to-use APIs. > have not found this to be the case with zig in general. Dunno how general it is, but TFA we're discussing here contains an example, so AFAICS it seems at least a little too common.

7bit 1y ago

Your argument implies that good documentation is not an improvement, which of course is wrong. It also belongs to the task of improving code. Why would you move away after half-assing the API, when you can add the docs and whole-ass it instead?

crote 1y ago

On the other hand, not writing documentation also has a cost. Code is rarely written from start to finish in a single session. Would you rather spend 5 minutes before you do a git commit to write down some very basic documentation, or spend an hour rediscovering it when you pick up development two weeks later? Nobody is expecting extensive and well-polished documentation here, but is a "Flags X, Y, and Z are mandatory, buffer A is required: I tested with 10MB, smaller might be fine too" really too much to ask for? Is the time you saved by not writing that one line worth someone else spending several hours figuring out how to do a "hello world"?