This repository was archived by the owner on Mar 25, 2018. It is now read-only.
Repository navigation
This repository was archived by the owner on Mar 25, 2018. It is now read-only.
Meeting #1 #119
Description
Let's get this async meeting thing started. There's two topics I want to cover:
- Where should we put the guides
- What guides do people want (not necessarily what they personally are volunteering to write, just want to document our current doc deficiencies for now)
Anyone have any input on these topics, or more topics they want to discuss? I'll leave the issue open for discussion for 72 hours to give people some time to comment.
Activity
Qard commentedon Jan 9, 2017
My vote is for guides to be part of the website as they are more abstract than the reference docs and therefore probably don't need as much effort to stay in-sync with the codebase. It'd probably also make translation easier being part of the website. Might be good to get some input from @nodejs/localization though.
As for what guides I'd like to see, some intros to popular routing frameworks and websocket libraries would be good. A guide on making cli tools would also be good.
sam-github commentedon Jan 9, 2017
Agree, and would like to see these guide-like materials moved from nodejs/node/doc/guides to the Website repo:
I also think https://github.com/nodejs/node/blob/master/doc/topics/domain-postmortem.md should be moved to a documentation/Website guide, it includes important information on the limitations of Domains, and gives context to their deprecation.
The other three "guides" in https://github.com/nodejs/node/tree/master/doc/guides are not documentation guides, they are internal docs on Node.js mainteance process and procedure, do not need to be on the website, are not actually "guides" in website/documentation terms, and should be moved up a directory into https://github.com/nodejs/node/tree/master/doc for now to be beside the other onboarding docs.
A case has been made that those onboarding/collaborator docs deserve a location that is not in
doc/, which I agree with, its problematic to have things indoc/that don't show up in the doc website, but maybe one thing at a time, because there are lots of ways of reshuffling those files, but the situation with guides is more clear cut, IMO.evanlucas commentedon Jan 9, 2017
I think we should get all guides that are intended for end users of node to the website as well. I think they should be moved to https://nodejs.org/en/docs/guides/ in particular.
I agree with @sam-github that we should wait on the onboarding/collaborator docs and just do the enduser guides as a first step.
eljefedelrodeodeljefe commentedon Jan 9, 2017
Strongly against putting it on the site as no-one reads it there. At least the link should be prominent in the API docs. Especially the design inconsistency between the sites makes it really unconnected, for visitors.
A good example for structure of docs is Kubernetes http://kubernetes.io/docs/, which makes a mindful combination guides, tutorials, docs, and API docs.
Qard commentedon Jan 9, 2017
👍 for a clearer distinction between user-focused guides and collaborator-focused guides.
laosb commentedon Jan 9, 2017
Having a separated guide site like many projects do would be great.
Qard commentedon Jan 9, 2017
Sorry if it was unclear, but I'm not arguing for putting guides somewhere other than reference docs in terms of website navigation, only code location.
evanlucas commentedon Jan 9, 2017
@eljefedelrodeodeljefe do you have any data to back that up? It is directly accessible on the page labeled "DOCS" from the website.
laosb commentedon Jan 9, 2017
I mean, a separated repo and site.
eljefedelrodeodeljefe commentedon Jan 9, 2017
@evanlucas Of course not. What a question.
eljefedelrodeodeljefe commentedon Jan 9, 2017
It#s about making good user experience decisions. Simply counting the clicks you need to do to get there, and there prominence on the site is revealing enough.
eljefedelrodeodeljefe commentedon Jan 9, 2017
@evanlucas Also SEO: goovling for Node docs, brings up API docs first. Please be constructive
evanlucas commentedon Jan 9, 2017
Googling for
node docsbrings up https://nodejs.org/en/docs/If one were to follow the link in the first search result, they are brought to the main docs page that has api documentation for the two latest versions (LTS and Current). Directly below the API document is a link called
Guides. I'm suggesting that we place the guides on the page titledGuides.Here is a screenshot of the docs page:
The list item labeled
Guideslinks to the page that I suggested (https://nodejs.org/en/docs/guides/)As you can also see from the first screenshot, the
Guideslink is also prominently displayed to the bottom right of the first search result.Qard commentedon Jan 10, 2017
@laosb Are you implying just a different subdomain like docs.nodejs.org, or a fully separate site like rust has with rustbyexample.com? I would prefer a closer relationship with the official website, but I think a separately managed docs.nodejs.org website might be fine. I worry a bit about the extra burden of taking on the website management aspect of that though, which would essentially be duplicated effort from what the existing website wg already does.
sam-github commentedon Jan 10, 2017
I think this is getting side-tracked. First thing is to get the "guides" that are invisible to our users because they exist only in markdown in the nodejs/node repo onto the website where the other guides are.
I've no objections to rearranging the website, once it has content, if someone thinks they have some constructive suggestions for rearranging it, speak up.
Its not clear to me that the docs WG controls the website, though, or should. At one point, wasn't there an active Website WG? Aren't they still active? @mikeal
4 remaining items
laosb commentedon Jan 10, 2017
Having a separated
guide.*.tldis what big projects usually do. Putting them inside website will lead to confusions. Many would search forguideand they may won't find the Guide hiding in DOCS section, because in many projects they're separated, eg Meteor, RoR, Vue, etc. Obeying a common pattern would decrease the time to understand the website.Qard commentedon Jan 13, 2017
Closing now.
We should present our suggested guides markdown location to the CTC. It looks like the consensus currently is to put those in http://github.com/nodejs/nodejs.org. The accessibility issue will need further discussion.
Is that a fair assessment? If anyone disagrees with that conclusion, speak up. Otherwise, I think we can present our decision to the CTC.
eljefedelrodeodeljefe commentedon Jan 13, 2017
Hmm. I think this doesn't catch the topic completely.
nodejs.org/docs/guidesor similar. At least I would strongly oppose this.Qard commentedon Jan 13, 2017
Yep, my thought was just to propose to the CTC that we move the code and we can deal with the accessibility concerns later. As I expressed, it seems like that needs deeper discussion.
eljefedelrodeodeljefe commentedon Jan 13, 2017
Okay in that case. Thx.
Qard commentedon Jan 13, 2017
@evanlucas Would you mind presenting this to the CTC? Also, do you have powers to add
ctc-agendalabel to this? The label seems to not exist yet in this repo and I don't appear to have the power to create it.sam-github commentedon Jan 13, 2017
@nodejs/tsc Can someone with the power arrange that all doc WG members (https://github.com/nodejs/docs/blob/master/README.md#current-documentation-wg-members) have ability to configure labels and do other routine maintenance of the nodejs/docs repo? @Qard doesn't seem to have that power, ATM.
Trott commentedon Jan 13, 2017
Of the four guides that are currently in the
nodejs/noderepository underdoc/guides, three of them are specific to contributing to core. I personally think it makes sense to have those with the source code and may not make a whole lot of sense having them on the nodejs website.Qard commentedon Jan 13, 2017
Yep, that's our feeling too. Contributor-specific stuff can stay in nodejs/node.
Trott commentedon Jan 13, 2017
Need to be added to the @nodejs/documentation group to have those privileges in this repo. I'll add @Qard right now, but if someone else wants to compare the membership of that team with the membership of the WG and provide a single comment (or separate issue) listing members to be added/removed, that would probably be good.
EDIT: Whoops, @Qard is already a member. Either someone beat me to it or I don't know what I'm talking about. (Maybe both, even.)
EDIT 2: Double whoops, you're talking about creating labels rather than applying them. Yeah, I have no idea. I'll create the label though if no one has beat me to it.
Trott commentedon Jan 13, 2017
I created a
ctc-agendalabel, but note that the tooling that creates the agenda for meetings won't pick it up if the issue it is applied to is closed. So be sure to create a new issue or re-open this one.evanlucas commentedon Jan 13, 2017
I'll open an tracking issue at nodejs/node so we can get it in for the next meeting
Qard commentedon Jan 13, 2017
Great, thanks all!
sam-github commentedon Jan 13, 2017
@Trott I agree with you, see #119 (comment). There are doc/guides and doc/topics, and I think there is consensus that info about maintaining the node repo itself shouldn't be on the website, and shouldn't have been called "guides" in the first place.