4 ms·

This will help people browsing code in github, but folks browsing code in their IDE will most likely be lost, as the documentation you advice to put into "READM

by jlg23 6y ago

This will help people browsing code in github, but folks browsing code in their IDE will most likely be lost, as the documentation you advice to put into "README.md"s should, IMHO, be in the module/package documentation in the source. One can still link to those from the global README.md

snicker7 6y ago
READMEs and API docs aren't mutually exclusive. But they cover different scopes. READMEs are more suited for high-level documentation, focusing on the /why/ instead of the /how/.
baby 6y ago
I'm not sure I understand why someone in their IDE would be lost, you can't read README.md and see the file structure in your IDE? Documentation in the source is different from a directory organization documentation IMO. Rust has a lot of tools to write good documentation in source, and it is here to help produce good documentation for users of a library, not to explain how to contribute to the code or understand how everything is architected.
- jlg23 6y ago
  > I'm not sure I understand why someone in their IDE would be lost, you can't read README.md and see the file structure in your IDE? Of course one can see the files. But I rarely deal with "files" in my IDE, I deal with packages/namespaces/modules/functions/classes/methods. The natural place to put architecture documentation would therefore be the top-level code unit (e.g. package/module/namespace), to which one can easily navigate when viewing docs. > Documentation in the source is different from a directory organization documentation. Is it, given that directories tend to be organized around code units (again: packages/namespaces/modules/classes)? It is thinkable to store code in databases (see Dylan's IDE, either implemented or it was on the roadmap, I don't remember) and all the architecture documentation not directly attached to semantic units of your code would be lost.
  - hashhar 6y ago
    100% agree. A very good implementation of your ideas can be found in the Redis codebase. Most important files have a long doc comment in the beginning. See https://github.com/redis/redis/blob/unstable/src/ziplist.c https://github.com/redis/redis/blob/unstable/src/ziplist.c for an example.
    - baby 6y ago
      your example is a comment of the code/implementation, related to the actual file, not to the architecture
  - baby 6y ago
    I still don't think this is a good idea, after having worked a lot with Golang and Rust doc, the documentation generated from comments is targeted to users of the library, not contributors. (And Rust/Golang have the best documentation system out there of any language I have ever seen). For example, documentation in Golang does not follow your file structure, it just pulls up any public API comment and displays it. It makes sense, why would I care about how these functionalities are implemented and architected as a user? Second point: a system has different types of languages and ways to organize things, so it’s not always clear where to look for doc. Whereas a README is always obvious.

by jlg23 6y ago

snicker7 6y ago

READMEs and API docs aren't mutually exclusive. But they cover different scopes. READMEs are more suited for high-level documentation, focusing on the /why/ instead of the /how/.

baby 6y ago

I'm not sure I understand why someone in their IDE would be lost, you can't read README.md and see the file structure in your IDE? Documentation in the source is different from a directory organization documentation IMO. Rust has a lot of tools to write good documentation in source, and it is here to help produce good documentation for users of a library, not to explain how to contribute to the code or understand how everything is architected.

jlg23 6y ago
> I'm not sure I understand why someone in their IDE would be lost, you can't read README.md and see the file structure in your IDE? Of course one can see the files. But I rarely deal with "files" in my IDE, I deal with packages/namespaces/modules/functions/classes/methods. The natural place to put architecture documentation would therefore be the top-level code unit (e.g. package/module/namespace), to which one can easily navigate when viewing docs. > Documentation in the source is different from a directory organization documentation. Is it, given that directories tend to be organized around code units (again: packages/namespaces/modules/classes)? It is thinkable to store code in databases (see Dylan's IDE, either implemented or it was on the roadmap, I don't remember) and all the architecture documentation not directly attached to semantic units of your code would be lost.
- hashhar 6y ago
  100% agree. A very good implementation of your ideas can be found in the Redis codebase. Most important files have a long doc comment in the beginning. See https://github.com/redis/redis/blob/unstable/src/ziplist.c https://github.com/redis/redis/blob/unstable/src/ziplist.c for an example.
  - baby 6y ago
    your example is a comment of the code/implementation, related to the actual file, not to the architecture
- baby 6y ago
  I still don't think this is a good idea, after having worked a lot with Golang and Rust doc, the documentation generated from comments is targeted to users of the library, not contributors. (And Rust/Golang have the best documentation system out there of any language I have ever seen). For example, documentation in Golang does not follow your file structure, it just pulls up any public API comment and displays it. It makes sense, why would I care about how these functionalities are implemented and architected as a user? Second point: a system has different types of languages and ways to organize things, so it’s not always clear where to look for doc. Whereas a README is always obvious.