doc: add core-structure topic doc #6885
Conversation
| - Tests & Benchmarks (`test/` & `benchmark/`) | ||
| - Internal / Build Tooling (`tools/`) | ||
| - Dependencies (`deps/`) | ||
| - .dotfiles |
There was a problem hiding this comment.
Since this is more or less a TOC, can you maybe make these links?
There was a problem hiding this comment.
+1 I think this could be simplified into a TOC with less copy, and move explanations of each section to their section
There was a problem hiding this comment.
CHANGELOG?
Huh? That's a "CAPITALS" file.
There was a problem hiding this comment.
/doc/changelogs/*.md
On May 23, 2016 7:45 AM, "Jeremiah Senkpiel" [email protected]
wrote:
In doc/topics/core-structure.md
#6885 (comment):
+## Top-Level File & Folder Structure
+
+At the root of Node.js you have a set of files and folders that can be roughly
+identified as the following:
+
+- CAPITALS documentation files
+- Documentation (doc/)
+- Top-level Build Tooling
+- JavaScript "standard" Library (lib/)
+- C++ "native" Source (src/)
+- Tests & Benchmarks (test/&benchmark/)
+- Internal / Build Tooling (tools/)
+- Dependencies (deps/)
+- .dotfilesCHANGELOG?
Huh? That's a "CAPITALS" file.
—
You are receiving this because you are on a team that was mentioned.
Reply to this email directly or view it on GitHub
https://github.com/nodejs/node/pull/6885/files/45979673c36c8d2e485bcd06617042703f0fa5e6#r64234969
There was a problem hiding this comment.
We already have that, I don't understand...
- Documentation (
doc/)
There was a problem hiding this comment.
Nothing in your proposed doc mentions changelogs in any way, either as a capitals file or in the docs, the changelogs are now split between the root CHANGELOG.md file and separate files under /doc/changelogs/*.md.
This document covers the basics of how Node.js is structured, in an attempt to make it easier to contribute to.
Fishrock123
force-pushed
the
core-structure-doc
branch
from
4597967 to
1b02b91
Compare
|
+1 on more detail. I think people wanting to read this can hardly be overwhelmed. I can tell with my experience from the Python docs, which fills binders (I actually printed a chapter). I am missing the reference to a discussion, but in any case I think it is a good idea to omit 80 chars line length rule here. Since the texts are rather long and just two groups of users need to use - author [singular predominantly] and readers, but not maintainers of a high frequency api doc page - boilerplate work for the author should be kept to a minimum to facilitate a better text piece. +1 for Also note that I was considering having sub folders for topics in the doctool-PR for topics (once I get there), so if for me I'd put this one hierarchy level below into some category like "internal" (tbd). Since it got mention, let's don't make this too much TOC-like |
| The API docs are constructed from the markdown files within the `doc/api/` | ||
| folder. | ||
|
|
||
| The documentation also includes topic documents such as this one such as this, |
|
Another thing: Combine all the tooling, or keep it separated? |
| The documentation also includes topic documents such as this one such as this, | ||
| how-to guides, the `node.1` [manual page][], and an archive of Technical | ||
| Committee meeting notes. | ||
|
|
| @@ -0,0 +1,202 @@ | |||
| # Node Core's Internal Structure | |||
|
|
|||
| This document covers the basics of how Node.js is structured, in an attempt to | |||
There was a problem hiding this comment.
Nit:
- remove the comma
- consider removing everything after the comma too
- s/covers the basics/explains/
| make it easier to contribute to. | ||
|
|
||
| Note: The Node.js codebase is in a constant amount of flux, things can and will | ||
| change over time, and so also parts of this document will go out of date over |
There was a problem hiding this comment.
Suggestion: get rid of the comma and everything after it and replace it with a separate sentence:
...change over time. If you find something in the document that seems incorrect, file [an issue](link to issue tracker here) or a pull request(link to pull request creation form here).
|
Just an idea: I wonder if GitHub isn't the best way to get this into shape just yet. I wonder if it might be better as (for example) a public Google Doc that people can make suggested edits to that you can accept or reject. Once it's mostly in shape, then it can be copy/pasted into your branch and show up in this PR. While it's valuable to track conversation/back-and-forth, it's really slow-going to leave comments about things like comma splices. The GitHub back-and-forth is great for content discussions, though. |
rvagg
force-pushed
the
master
branch
2 times, most recently
from
c133999 to
83c7a88
Compare
|
ping @Fishrock123 ... still want to pursue this? |
|
Just discovered this (thanks to @jasnell). This is something I've wanted for a while, I think it will be really helpful for new contributors. @Fishrock123 if there's any way I can help with this let me know. |
|
I wrote a somewhat related doc ages ago which lives here, though I can't seem to find any links to it on the website anymore. Not sure if any of the content of that is valuable here. |
|
@Fishrock123 do you still want to follow up on this? I would otherwise close this. And if not - I think @gibfahn you would be up for opening a new PR for this? |
|
Would like to open a PR for this, just a question of finding time. |
|
Let's close this one. We can revisit later if/when someone finds the time. |
Checklist
Affected core subsystem(s)
doc
Description of change
This document covers the basics of how Node.js (node core) is structured, in an
attempt to make it easier to contribute to.
Things to note / TODO:
Node.jsvsnode corevsnodelanguage. Idk which to use where either.Additionally, some lines go beyond the line limit because they are part of markdown formatting and not all markdown formatters are able to properly interpret those parts when split across lines (in lists, for example).
cc @nodejs/documentation