Comments (24)
- Migrate stuff from nodejs/nodejs.org over to nodejs/node
- Figure out what to do with the knowledge base content
- Lint code samples in docs?
Not sure if we should discuss the IA strategy again soon to decide how to handle the content migration. Might be a good idea.
from docs.
User's that land on a page like this one https://github.com/nodejs/nodejs.org/blob/master/locale/en/docs/guides/simple-profiling.md which outputs to https://nodejs.org/en/docs/guides/simple-profiling/ can easily get confused about what version of node the doc is referring to. There is a PR open for the page here nodejs/nodejs.org#449 but there doesn't seem to be a good pattern here to refer to how this or other articles will describe how node works at different versions within the single document. In this case, for example, the tool referenced for 4.x is no longer in master and requires going into 4.2.4 on git to access here https://github.com/nodejs/node/tree/v4.2.4-proposal/tools/v8-prof
I realize this is somewhat specific to this article, but I think it illustrates the need to have more structure around this type of documentation staying correct for a range of versions.
@chrisdickinson thanks for all your dedication to the docs
from docs.
- providing clear, updated examples for each API
- providing basic, straightforward examples as early as possible in each
document
On Jan 18, 2016 7:41 PM, "Chris Dickinson" [email protected] wrote:
Hi all —
I've noticed that it can be overwhelming to look at the state of the docs
and try to pick a single thing out to work on. There are a ton of
things that need improvement, and everyone sees different deficiencies in
the docs. Further complicating matters, the docs are a relatively tight
space to work within — it's really easy to end up stepping on other folks'
toes when making larger changes.With that in mind, I'd like to run a quick exercise. In this issue, I'd
like you to list as many different features, tools, or docs that you think
need work. At this point this is unranked listing — no +1's or votes at
this point, please! Feel free to repeat items others have said, though.
Examples might be:
- Doc tool needs to validate links
- Need internationalization strategy for node docs
- Create "guide" section
- Create glossary, define all jargon terms within
- Docs search
- Better docs on child process
I will close this issue at the end of the week and put forward a
roadmap for discussion./cc @nodejs/documentation
https://github.com/orgs/nodejs/teams/documentation—
Reply to this email directly or view it on GitHub
#59.
from docs.
Documenting what things throw. Rust has it in their API docs like this: https://doc.rust-lang.org/std/string/struct.String.html#method.reserve
One case that has burned us at New Relic was process.memoryUsage
which can throw an exception when file descriptors are exhausted. This is because (at least on linux) it opens a file to check the memory and just raises the exception. Theoretically it could throw under other situations too since it is a FS operation that just raises its errors.
from docs.
I think it could be really nice to revamp the error messages errors have in Node.
I think doc pages should attempt to explain how to deal with said errors.
I'd like to discuss the possibility of comments on API methods like some other languages have.
from docs.
Yeah...I really wish node had actual error codes and different error types. It really sucks having to parse the message to attempt to derive some actual context from the errors we get. It's kind of terrible. Better docs would help, but I think that's only part of the solution.
from docs.
- Documenting backwards compatible interfaces fs.writeFile(file, data[, options], callback) for example could be called with
options
as an encoding or an object with encoding. But this fact is not clear. - Links between the documents. In fs.writeFile(file, data[, options], callback) for example
encoding
is mentioned many times but never linked to what encodings are supported and what they mean. - Either links or expand docs for interfaces referenced externally. In FS for example there are many references to essentially man pages, but no links. So like chmod(2) could be replaced with a link or explanation of what
chmod(2)
means.
I think I've found where I want to focus on. I've done a lot of with FS and found many skeletons.
from docs.
Linking in nodejs/node#1684
from docs.
- For each API call, documenting from which version this API was available.
Yes, I know that I can go look at older versions of the API, but it's a pain. I would prefer always looking at the latest version and figuring out from there whether the API I want is available in that version or not.
- For each API call, which errors are "thrown" from it.
from docs.
That a good point @giltayar
One of the documentation features I really liked from Android was that you could change you API Level (api version) and it would just grey out things that aren't supported on that version.
Check out this and change the API Level
drop down and you'll see things change as you go. It also greys parts out on pages that weren't in that version.
from docs.
@DavidTPate - that's really really cool, and a lot of time must have been invested in that. But sometimes the simplest is the best in terms of value for effort: when adding an api, or changing it, just documenting the version number it was added/changed in. This will be for posterity, since the documentation is (I'm assuming) incremental.
Also, for me, doing it from this point onward is good enough. Again, in terms of value for effort, going back historically and figuring things out isn't worth the effort.
from docs.
The naming of anchors. For instance, the link to fs.symlink
is fs.html#fs_fs_symlink_target_path_type_callback
, which is both weird on the eye and impossible to type yourself if you're searching for a function's doc.
fs.html#symlink
or even fs.html#fs.symlink
are conceivable alternatives.
from docs.
hi! i'm from the @nodejs/inclusivity WG.
we fielded an issue about experiences joining large open source projects: nodejs/inclusivity#86
based on this, we plan on developing a Getting Started in Node.js
tutorial that can serve as a friendly and approachable guide to open source contribution in Node. we hope to collect and organize a lot of the current work, as well as develop some new content, and eventually have it on nodejs.org
the tracking issue for this is here nodejs/inclusivity#96
(it's empty rn as we just approved it as a program in our meeting today)
would love to collaborate with ya'll
from docs.
@Zirak That would break any existing links people have made to the docs from elsewhere. It may be possible to add extra anchors for cleaner names in the future doctool though. I'll add that to the list of stuff to consider.
@ashleygwilliams As I mentioned in that tracking issue, internals docs is a thing we want to be better at, which should help with that.
from docs.
@Qard You're right. A mediocre solution would be to just have both, something like:
<a [...] id="fs_fs_symlink_target_path_type_callback">#</a>
<a [...] id="symlink"></a>
from docs.
I know @ashleygwilliams has worked on for the npm docs, but we badly need something to clarify what unlink(2)
, and similar do. man
page explanations, and links to a generalized posix doc or similar documentation on what specific things at very least generally do. This is a particularly bad problem in the fs
docs.
from docs.
i have a module that converts 'unlink(3)' to a link. would love to make a PR. i was planning on it months ago and just forgot 😅
from docs.
Hi! Sorry if it already exists in the docs and I missed it.
I would love to see some higher level design and architecture documentation of nodejs.
Maybe some of it can link to v8 docs, but a whole picture that can get a beginner to wrap around his head about how exactly is nodejs built. All the way to the even loop, including design principles, and key optimization points.
An excellent example of this is Kafka's docs both the getting started and the design parts
from docs.
I'm imagining a target audience index similar to the API docs Stability index. Guides and Topics would have a target audience (beginner, intermediate, advanced) indicator at the top of the Topic/Guide possibly linking to prerequisite Guides and/or Topics.
We could provide a TOC Guide for each target audience--beginner, intermediate, and advanced--each of which could provide "pathways" to steer users to appropriate Topics based upon their skill levels. Granted, determining the skill level of a given Topic might be non-trivial.
I imagine API docs would almost always be advanced, as they are provided as a reference with boilerplate usage examples. A notice saying "This is Advanced stuff" especially if there are links to relevant Guides and Topics, would help direct users to Guides and Topics appropriate for their skill/knowledge level.
For example, a path for beginners:
- What is Node.js?
- Guide to using Docs
- Installation
- Hello World
- Globals
- Modules
- Events
- etc.
Intermediate:
- First HTTP server
- Intro to streams
- Debugger
- Net
- Child Process
- ES2015 Features
Advanced:
- Buffer
- Cluster
- Crypto
- TLS/SSL
- C/C++ Add-Ons
- VM
from docs.
@techjeffharris Good list. I guess streams
could be several times in all of these categories with varying topics. I'd imagine something curated like this piece of howtonode for it, that would explain streams
not only as a class, but a powerful programming technique.
from docs.
Thanks! The list was from the top-of-my-head to get the ideas flowing. Great article, though it could be even better if kept up to date with latest changes and best practices.
from docs.
OK, closing this now, slightly later than promised. What follows is a distillation of what's been mentioned in this issue, grouped into related chunks of work. This is not the roadmap itself, and it is not prioritized. I will propose a ROADMAP.md
in a subsequent PR.
Content
- Identify common topics to pull into topic docs
- Encoding — noted extensively in fs and buffer docs
- Blocking vs. non-blocking calls.
- Glossary for jargon terms
- Syscalls
- Improve reference documentation
- Provide useful examples for every API method
- Remove non-reference material from reference docs
- Guides & Tutorials
- Better error documentation, "how to deal with errors"
- Provide walkthrough examples for each module
- Adapt knowledge base content into new guides and tutorials
- Internal docs
- Work with Diversity WG on contributor tutorial doc
- High level architecture and design of node
- Event loop, design principles, etc
- Identify other docs to create
Metadata & Features for Readers
- Making sure guides and tutorials note pertinent version
- Add version information per API method (added, removed, changed)
- Internationalization strategy for docs
- Target audience index
- Document API signatures including what errors may be generated and how they're propagated
- Backwards compatibility in api signatures
- Docs search
- Automatically linking syscalls to syscall doc
- Automatically linking types in API signatures
Tooling (for authors)
- Improve anchor names (let authors pick an anchor name in addition to autogenerating it)
- lint code samples in docs
- turn docs WG guidelines into markdown linter rules
- migrate docs from nodejs/nodejs.org to nodejs/node
- New docs tool for guides (remark)
- Migrate API docs off old doctool towards remark
- Document Docs WG process & execute on it
from docs.
Oh, and I almost forgot to mention: Thank you all for participating in this!
from docs.
Great Distillation!
from docs.
Related Issues (20)
- Node v6.3.1 docs: net.Socket HOT 1
- StackOverflow Documentation for Node.js HOT 5
- Circular reference for OS Constants HOT 3
- http ClientRequest documentation unclear about inheritance when visually scanning HOT 2
- .read() stream not fully explained HOT 9
- Rough Meeting Notes (2016-12-01 @ NINA) HOT 8
- What errors can be thrown?
- Async meetings HOT 6
- How-to use LetsEncrypt Guide HOT 13
- Meeting #1 HOT 33
- Add @vsemozhetbyt? HOT 4
- Meeting #2 HOT 2
- descriptions of "The module Object"'s property are not clear HOT 1
- clarity on asynchronous methods throwing exceptions HOT 2
- http.ClientRequest is missing some methods HOT 3
- Package documentation (how to intl) HOT 1
- Decharter this Working Group? HOT 8
- Better wording for modules_all_together HOT 3
- Suggestion: Return type in function declaration & possible option to view types by clicking HOT 2
- Improve the words usage in socket.setTimeout() definition HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from docs.