Comments (7)
👍 from me. 😸
from docs.
It seems to me that one of the major blockers is the "shares responsibility for doc/api
with the core team" bit; where core wants to have API docs tied closely to API so new PRs affecting API can have "update the docs too" enforced in the same way as "add a test" is enforced. With the docs living elsewhere or being managed by a separate group this becomes more cumbersome and may impact the pace of progress.
So, perhaps its worth exploring the idea of using tooling to solve the conflict. e.g. the API docs that core owns are purely descriptive and have a well defined format. Perhaps its even JSON or semi-JSON, with fields such as "arguments", "errors", "return value", maybe going so far as to include a basic description but stopping short of being complete. Then tooling could be used to generate the final docs by pulling in this formal data and combining it with data owned by the docs group that fleshes out the formal descriptives with expanded descriptions, examples, warnings, links to tutorials, etc. A case could be made here that what core needs to own is very limited in scope and it would be healthier for the docs as a whole for that scope to be well defined so that we can allow for clearer distinction between contributing code and contributing docs when it comes to core's API docs (great coders are rarely great documenters and vice versa so how about we make our processes allow for that?). At a minimum, having a non-freeform API doc specification format would help with consistency, we keep on making note of how inconsistent it all is (e.g. nodejs/node#4362 (comment)). /cc @jasnell
from docs.
I definitely like the idea of separating this out and having a more machine
readable root format for the API docs so long as there is solid effort
going into refining those into polished rich documentation. I can even take
a stab at writing up an initial version.
On Jan 8, 2016 5:18 AM, "Rod Vagg" [email protected] wrote:
It seems to me that one of the major blockers is the "shares
responsibility for doc/api with the core team" bit; where core wants to
have API docs tied closely to API so new PRs affecting API can have "update
the docs too" enforced in the same way as "add a test" is enforced. With
the docs living elsewhere or being managed by a separate group this becomes
more cumbersome and may impact the pace of progress.So, perhaps its worth exploring the idea of using tooling to solve the
conflict. e.g. the API docs that core owns are purely descriptive and
have a well defined format. Perhaps its even JSON or semi-JSON, with fields
such as "arguments", "errors", "return value", maybe going so far as to
include a basic description but stopping short of being complete. Then
tooling could be used to generate the final docs by pulling in this formal
data and combining it with data owned by the docs group that fleshes out
the formal descriptives with expanded descriptions, examples, warnings,
links to tutorials, etc. A case could be made here that what core needs to
own is very limited in scope and it would be healthier for the docs as a
whole for that scope to be well defined so that we can allow for clearer
distinction between contributing code and contributing docs when it comes
to core's API docs (great coders are rarely great documenters and vice
versa so how about we make our p rocesses allow for that?). At a minimum,
having a non-freeform API doc specification format would help with
consistency, we keep on making note of how inconsistent it all is (e.g. nodejs/node#4362
(comment)
nodejs/node#4362 (comment)). /cc
@jasnell https://github.com/jasnell—
Reply to this email directly or view it on GitHub
#50 (comment).
from docs.
I think just pulling all the non-reference content out into guides is probably enough. Code PRs would have to include reference docs, but in-depth guides could be written separately.
from docs.
@jasnell, @rvagg: This is an interesting approach! However, I'd like to avoid new tooling until we:
- Figure out membership,
- Have a meeting to discuss direction,
- And become ratified.
Which isn't to say we can't have a discussion around doc tooling (which I agree, needs to improve!), but that we shouldn't focus on doc tooling as a key piece of getting the WG stood up.
Process discussion is totally viable at this stage, though, especially in terms of reducing friction between core and the Docs WG. Perhaps the Docs WG doesn't block code PRs for doc review, but instead has a weekly task of editing newly merged documentation — the only thing the WG could block would be releases, in order to make sure the docs are in a good state?
from docs.
We're ratified!
from docs.
very goood!
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.