Nodejs.dev: User Feedback: Node.js Docs Survey

[bnb]

I brought up a discussion around the Node.js docs and possibly sending out a survey via official means of communication in today's User Feedback session, specifically because of some of the discussions that we've had in this group.

I'd love to know if y'all feel this is a good idea. If you do, we can and should begin formulating questions around what we'd like to ask.

Some possible topics for questions:

• Likes / dislikes around the current state of the docs
• What the project could do to improve the docs
• Rating the current docs, from 1/10
• ???

[amiller-gh]

Love this – more data is always better. Let me get back to you with a list of ideas later this week 👍

[raisinbread]

In my experience, people tend to (especially when frustrated or new) to just say "the docs suck". The more specific you can get, the better. Your examples seem pretty broad, so I might suggest something more like:

• Which sections need the most attention, as far as quality is concerned?
• Which APIs need examples or extended guides (in addition to reference material)?
• Which Node.js concepts do you feel are the most difficult to understand?
• What format(s)/language(s) would you prefer they are delivered in?
• What do you feel is missing?
• How could we make the docs more accessible for newcomers?
• How can we make the docs more streamlined for pros?

I would love to help and/or be more involved, if you're looking for someone to pitch in.

[amiller-gh]

@raisinbread sorry for the insane delay!! We'd love your help with pushing this forward. Think you can get a draft survey together on a Google form that we can all co-edit to help us move on this? Would be much appreciated 🙏

Would love for the questions to be quantitative enough for a follow up round after we publish new documentation to track improvement over time.

[erichodges]

I'm interested in helping. I'll have to look at Google forms as I have not used them yet.

[raisinbread]

@amiller-gh Sorry to be slow on the reply as well. I can set up a doc for editing. Who should it be shared with? I guess maybe send me some email addresses to anderson.johnd at gmail?

@erichodges once we have the content nailed down, maybe we can get some help putting it in a form to distribute?

[erichodges]

@raisinbread Sounds good!

[keywordnew]

@raisinbread @erichodges y'all are awesome!

Happy to help with guidance on process or context if it comes up while you do this. Mentioning me on here is one way to loop me in.

[raisinbread]

@chowdhurian, here's a first stab. Happy to add you (or others) as contributors—just send me a note at the email address mentioned above. I'm just making these questions up based on my experience. Interested to hear your thoughts.

https://docs.google.com/forms/d/e/1FAIpQLSeG7h9P3kI-bxOigL70noC1gLte8AC28tOiReulf79n7aUtuw/viewform

@erichodges, I've added you as a contributor.

[erichodges]

LGTM :-)

[sagirk]

It's an amazing first stab, @raisinbread! 🎉

My two cents: I noticed that the first two questions have quite a long list of checkboxes. As a survey-taker, I'm thankful that they don't make me think more than I have to — checking boxes is definitely easier than filling up empty text boxes. 💯 On the other hand, too many checkboxes make the survey seem longer than it is, despite being a total of just eight questions.

Not sure if it's a good idea, but a good compromise that I can think of is providing the top five (arbitrary number) most popular/used options as checkboxes, and providing an empty others text box to capture unlisted options.

[raisinbread]

@sagirk I dig - I don't have enough context what that top five might be... could you suggest the short list? Happy to make another adjustment based on that.

[sagirk]

I don't have enough context what that top five might be... could you suggest the short list? Happy to make another adjustment based on that.

@amiller-gh @chowdhurian @bnb Do we have any analytics/data that might help inform this decision?

[raisinbread]

Bumping just to keep this moving: @sagirk, @chowdhurian :)

[keywordnew]

Hey @raisinbread! Thank you for pinging here!!! ✨

I've prioritized this to get back to this thread/issue within the next 24 hours 🙏🏽🙏🏽🙏🏽

[keywordnew]

For both of the following questions:

Which sections need the most attention, with respect to quality (typos, inaccurate, outdated, etc)?
Which APIs are most in need of examples or extended guides?

I'd suggest choosing a selection of 5 items, chosen for our resources and bandwidth to improve on those particular sections.

Over several iterations, we'd improve the overall state of the docs.

[raisinbread]

@chowdhurian We have a few options, and based on your comment, I'm not sure what you're suggesting. Can you clarify?

1. We can still do a "checkbox" type question, but list 5 or so items that we guess need ranking. I'd need help from your team to know which five to list.

2. We move to a "dropdown" type question, where the first question still lists all items, but we ask 3-5 separate questions like "which needs help the most?, which needs help 2nd most?, etc."

3. Move off of Google Forms and try another tool.

Happy to try any of these, so let me know what you think.

[keywordnew]

@raisinbread first, I want to apologize for the _extreme_ delay in responding. I hope that the information in this response will make up for the extended time.

To clarify my earlier comment, my meaning was closest to your point number 1. 🙆🏽‍♀️

I'd need help from your team to know which five to list.

I will suggest that the items that should go on that checkbox list are:

• [ ] Buffer
• [ ] Console
• [ ] Debugger
• [ ] Modules
• [ ] Streams

I welcome other people's input on the above. It may even be worth starting a new thread to identify the ones to be included but I'm concerned that we are getting too process-heavy and we should just get the survey out the door and iterate over time.

Further comments about the questions. I am including a second opinion about the questions that I hope makes the long delay incrementally less frustrating!

We can still do a "checkbox" type question, but list 5 or so items that we guess need ranking.

To keep the survey low-friction (which will help people complete it successfully), I think we could simplify the overall survey by rethinking the first 3 questions!

First, we can take it down to two questions. The first question can include the 5 selected checkbox items above and be phrased:

"In your opinion, which sections need the most attention?"

We would like to keep people from being put off by having relatively less familiarity with Node.js

The second question can help clarify with:

"Please specify what the docs you selected could use to be more useful for you. For example, these could be typo or inaccuracy fixes, bringing that doc up-to-date, examples, or extended guides. Feel free to be as brief or detailed as you want."

I think the above suggestions help improve the flow and coherency 👍

I am tagging @chrischu5, who has been super helpful with this survey feedback process and is available to give more feedback!

Thank you very much for being patient with us getting the information you need to get this survey out the door! 🙏🏽💖🙏🏽

[raisinbread]

@chowdhurian: Well, we're getting into the holiday season now, so I think that may slow things a bit for me... Happy to help if I still can, though. This was originally intended as a summer project. :)

Updated: https://docs.google.com/forms/d/e/1FAIpQLSeG7h9P3kI-bxOigL70noC1gLte8AC28tOiReulf79n7aUtuw/viewform

[sagirk]

Looks good @raisinbread! 🎉

For the first question, in addition to the five checkboxes, do we also want to keep an Others text box to allow the respondent to enter unlisted section(s)?

[raisinbread]

👍

https://docs.google.com/forms/d/e/1FAIpQLSeG7h9P3kI-bxOigL70noC1gLte8AC28tOiReulf79n7aUtuw/viewform

@sagirk @chowdhurian

[keywordnew]

we're getting into the holiday season now, so I think that may slow things a bit for me

That's 100pc ok! Most of open source work is based contributors' personal availability at any point in time. I very much appreciate your choosing to contribute a significant chunk of that finite resource towards the Node.js project! 💛

The questionnaire is solid! 💥

I'll surface this in the user-feedback initiative. Updates to follow.

[amiller-gh]

From today's meeting: @codeekage to bring to user-feedback meeting tomorrow. Leave comments on what additional data we'd like to collect and we'll iterate on it with that working group to get it out the door 👍

[codeekage]

Feedbacks:

So far, I was able to have the meet with the User Feedback group. 🎉

Currently, they are a little bit understaffed and I can’t move forward with creating and updating surveys. But the User Feedback group plan on creating a Node.js User Group Meet-ups that will help facilitate between the broader community and Node.js.

Suggestion:
Create a slide deck with some specific areas that we would love to cover. Not necessarily pointed out question (more like a scope) three questions are good enough.

We could discuss what areas we have high interest in, in our next meeting and I will be happy to get it back to the User Feedback group. 🙏🏼