Repository navigation
language reference should be standalone; external links should not be considered as documentation coverage #1666
Description
Activity
Fwiw, the Rust manual has links to github: https://doc.rust-lang.org/book/2018-edition/ch00-00-introduction.html Also, Zig is not stable yet.
The Zig docs are not linking to github because the docs are incomplete. The "This", "Errors", and "Await" sections link to proposals to change the documented behavior. What do you propose instead of linking to those issues?
The Source-Encoding section links to an issue where I explain the decision to specify the source encoding as it is. The docs contain the specification, and the issue contains the rationale. I suppose we could put the rationale in the official docs, but it's not necessary for anyone creating or consuming Zig code, so I don't think it belongs in the official docs. If people are curious why the decision was made or would like to contribute their own opinion, the docs give a link to follow to read more and post comments.
Let's revisit this when the language is complete and the docs are done. It's way too early for an issue like this.
- changed the title
[-]I think docs shouldn't have links to Github[/-][+]language reference should be standalone; external links should not be considered as documentation coverage[/+]on Oct 24, 2018
Imagine if the GNU C manual had links to Github. This seems silly to me. The worst is when people link to Wikipedia articles in their official docs, but I don't think you guys are doing that, at least! :)
Examples I was able to find:
https://ziglang.org/documentation/master/#This
https://ziglang.org/documentation/master/#Source-Encoding
https://ziglang.org/documentation/master/#Errors
https://ziglang.org/documentation/master/#Await