Gatsby: Quick question about contribution

[jonniebigodes]

This is not a issue per se with Gatsby.
More of asking an opinion about a contribution. Based on the comment by @LekoArts here and my subsequent reply. I've created a more pratical example, it's currently searching for blog posts using the said library.

With that out of the way i would like to ask the @gatsbyjs/docs team a couple of things:
1- Is it necessary a document that details the process? Or adjust the existing one to mention that this example exists?
2- If the said document is necessary, where should it be linked in the doc-links.yml? Under recipes or advanced tutorials is a more suitable place for it?

Feel free to provide feedback

[pieh]

Is it necessary a document that details the process? Or adjust the existing one to mention that this example exists?

Can you rephrase this question / add more context? I'm not sure what "the process" is.

[jonniebigodes]

@pieh let me start by apologizing for the hasty and rather short description for the question.

With that out of the way i'm going to elaborate on the topic.

In order to expand the documentation for client side search coupled with js-search located here, i took on the task to expand it. It was built based on the example provided by it's creator with the "gatsby twist"(pardon the bad pun) and it's rather generalistic.

Now during the process of revision/fine tuning of the documentation this question popped up:

Would it be possible to make a graphql query to e.g. the blog sites you have and put that into the searchIndex instead of grabbing a JSON file from the internet?

I think that would be more what people would want to do.

And based on my subsequent response:

Let's start from here, mop up the search documentation as most as possible and then expand the documentation if necessary. That question that was asked can be further added as a recipe far along the line, i don't mind creating it.

But before i could move onto another pull request that i'm currently working on, i thought ok...this a rather trivial question, transforming this to a example, can be done in a short time and with little effort.
Also it answer LekoArts question and possibly prevent future issues that can pop up here.

The example was finished monday and it currently offers a way to search for blog post titles and authors using js-search.
Based on that, it led me to create this issue.

What i meant to say for the first item in the issue text was, is it necessary to create a new document that showcases both premises?
Those being how to build a gatsby blog and how to create a client side search with js-search.

Or can the existing document for the client side search with js-search be updated with a reference that the example i've created exists?

And with the second item, what i meant to say is, if the documentation is really necessary where should it placed in the docs-yml file for it to be easy to reach? Under recipes or under advanced tutorials

Either way works for me, all is needed is feedback from your end.

[pieh]

Thanks for taking time to write this up. I'm not really person that can answer that (I have same questions myself all the time heh), but I will try to summon @marcysutton :)

Just my personal though process - don't take it as official Gatsby answer:

For this particular case, just thinking about audience that would read js-search docs:

• People who have setup Gatsby site already and want to add functionality - those should know how to build a blog, so extra information about setting it up isn't needed for them is only distraction. For them example could be abstract (use any method to grab pages data - be it http request as in your example, or graphql query to grab from Gatsby data layer)
• People who didn't use Gatsby yet, but are evaluating it for their project (checking if they can use js-search for their content with Gatsby) - should the information that they can do it be enough even if they can't use it yet? (because they lack information on how to actually build site with Gatsby)

[jonniebigodes]

@pieh no problem at all, i was kinda in a hurry when i wrote it and i'm the one that should be thankful for the heads up to clarify the issue and the feedback.

Now to the issue at hand, you basically you enumerated my thought process for this, at the lack of a better definition this looks like a bit of a "catch 22" situation, but i'll leave it to @marcysutton for a better clarification on how to proceed.

[marcysutton]

Hi there! After looking at the current sidebar, I think it makes a ton of sense to add another page for "Adding search with GraphQL". That would give people more choice of how to develop a search feature. A new GitHub issue would be a great place to start. Does that answer your question?

[jonniebigodes]

@marcysutton and @pieh thank you very much for the time and comments on this issue. I'm going to close it and going to polish a more revised issue regarding and then open a new issue and we move from there.