7 ms·

Writing good docs/examples takes a lot of effort. It would be a waste considering the amount of churn that happens in zig at this point.

geon 1y ago
Yes. For now, that effort is better spent writing clear test cases that can serve to illustrate the intended usage. While tests aren’t quite as good documentation as actual documentation, they are guaranteed to not be out of date.
dns_snek 1y ago
That's a false dichotomy, I'll take minimal bitrotten docs in a community wiki over no docs. There's no excuse not to at least have a stub that says "these features are evolving quickly but here are 10 open source projects that should serve as good references". Something - anything. As much as I like Zig, I dread returning to it after a few months of being out of the loop.
- 0x696C6961 1y ago
  It's not a false dichotomy, it's a bandwidth issue. I'd rather the core team focus on stuff like incremental compilation.
  - dns_snek 1y ago
    "No documentation" and "Core devs 'wasting' time on writing high quality documentation" aren't the only two options, that's what a false dichotomy means. Other options include but are not limited to providing minimal, low effort examples, high-level overview, linking to projects using these features, linking to relevant tests, commits, or source code, setting up an official community wiki and encouraging people to contribute.
    - deleted 1y ago
      [deleted]
    - 0x696C6961 1y ago
      "No documentation" was never presented as an option. Documentation exists. By treating "insufficient docs" as "no docs", you're the one making the false equivalency.
      - dns_snek 1y ago
        > Documentation exists Where does a beginner go to learn how to use the package manager these days? It looks like they still won't find any clues in the "Learn" section of Zig's website. There's a promising page titled "Zig Build System" in there which references a "Package Management" section, but when you click on it, it doesn't exist!
        0x696C6961 1y ago
        So in your mind, one missing section means "no documentation"? This isn't the checkmate you think it is, you're just moving goalposts. But to answer your question, it exists in the comments of the auto-generated build.zig.zon file
        dns_snek 1y ago
        It's not just "one missing section", and we're not just talking about some fringe language feature but the build system which is probably the most complex, important, and under documented part of the language. The official answer to complaints about missing documentation has always been "ask in Discord". Pretending that this isn't the case is just disingenuous. > But to answer your question, it exists in the comments of the auto-generated build.zig.zon file The comments document the file format of build.zig.zon, they don't tell you anything about how to actually use a dependency in your build system.
        kristoff_it 1y ago
        I've added more explanatory comments in the new template that ships with 0.15.1, also you might be interested in this video https://www.youtube.com/watch?v=jy7w_7JZYyw https://www.youtube.com/watch?v=jy7w_7JZYyw
DannyBee 1y ago
Only in a world where features are made without thought. Documentation is not just for your users. Writing the development documentation helps you make better features in the first place. The zig users on this thread seem to not understand this, and all seem to think documentation is a thing you write later for users when everything settles down. Or is somehow otherwise "in the way" of feature and API development speed. That is a very strange view. If writing developer documentation is having serious affect on your language feature velocity, you are doing something very wrong. Instead, writing it should make things move faster, becuase, at a minimum, others understand what you are trying to do, how it is going to work, and can help. Also, it helps you think through it yourself and whether what you are writing makes any sense, etc. Yes there are people who can do this all without documentation, but there are 100x as many who can't, but will still give high quality contributions that will move you along faster if you enable them to help you. Throwing out the ability to have these folks help you is, at a minimum, self-defeating. I learned this the hard way, because i'm one of those folks who can just stare at random undocumented messy code and know what it actually does, what the author was probably trying to do, etc, and it took years till i learned most people were not like this.
- 0x696C6961 1y ago
  You're conflating specs/RFCs with end-user documentation.
  - CRConrad 1y ago
    No, AFAICS GP wasn't conflating anything. Why would you think they were?

geon 1y ago

Yes. For now, that effort is better spent writing clear test cases that can serve to illustrate the intended usage. While tests aren’t quite as good documentation as actual documentation, they are guaranteed to not be out of date.

dns_snek 1y ago

That's a false dichotomy, I'll take minimal bitrotten docs in a community wiki over no docs. There's no excuse not to at least have a stub that says "these features are evolving quickly but here are 10 open source projects that should serve as good references". Something - anything. As much as I like Zig, I dread returning to it after a few months of being out of the loop.

0x696C6961 1y ago
It's not a false dichotomy, it's a bandwidth issue. I'd rather the core team focus on stuff like incremental compilation.
- dns_snek 1y ago
  "No documentation" and "Core devs 'wasting' time on writing high quality documentation" aren't the only two options, that's what a false dichotomy means. Other options include but are not limited to providing minimal, low effort examples, high-level overview, linking to projects using these features, linking to relevant tests, commits, or source code, setting up an official community wiki and encouraging people to contribute.
  - deleted 1y ago
    [deleted]
  - 0x696C6961 1y ago
    "No documentation" was never presented as an option. Documentation exists. By treating "insufficient docs" as "no docs", you're the one making the false equivalency.
    - dns_snek 1y ago
      > Documentation exists Where does a beginner go to learn how to use the package manager these days? It looks like they still won't find any clues in the "Learn" section of Zig's website. There's a promising page titled "Zig Build System" in there which references a "Package Management" section, but when you click on it, it doesn't exist!
      - 0x696C6961 1y ago
        So in your mind, one missing section means "no documentation"? This isn't the checkmate you think it is, you're just moving goalposts. But to answer your question, it exists in the comments of the auto-generated build.zig.zon file
        dns_snek 1y ago
        It's not just "one missing section", and we're not just talking about some fringe language feature but the build system which is probably the most complex, important, and under documented part of the language. The official answer to complaints about missing documentation has always been "ask in Discord". Pretending that this isn't the case is just disingenuous. > But to answer your question, it exists in the comments of the auto-generated build.zig.zon file The comments document the file format of build.zig.zon, they don't tell you anything about how to actually use a dependency in your build system.
        kristoff_it 1y ago
        I've added more explanatory comments in the new template that ships with 0.15.1, also you might be interested in this video https://www.youtube.com/watch?v=jy7w_7JZYyw https://www.youtube.com/watch?v=jy7w_7JZYyw

DannyBee 1y ago

Only in a world where features are made without thought. Documentation is not just for your users. Writing the development documentation helps you make better features in the first place. The zig users on this thread seem to not understand this, and all seem to think documentation is a thing you write later for users when everything settles down. Or is somehow otherwise "in the way" of feature and API development speed. That is a very strange view. If writing developer documentation is having serious affect on your language feature velocity, you are doing something very wrong. Instead, writing it should make things move faster, becuase, at a minimum, others understand what you are trying to do, how it is going to work, and can help. Also, it helps you think through it yourself and whether what you are writing makes any sense, etc. Yes there are people who can do this all without documentation, but there are 100x as many who can't, but will still give high quality contributions that will move you along faster if you enable them to help you. Throwing out the ability to have these folks help you is, at a minimum, self-defeating. I learned this the hard way, because i'm one of those folks who can just stare at random undocumented messy code and know what it actually does, what the author was probably trying to do, etc, and it took years till i learned most people were not like this.

0x696C6961 1y ago
You're conflating specs/RFCs with end-user documentation.
- CRConrad 1y ago
  No, AFAICS GP wasn't conflating anything. Why would you think they were?