devrel icon indicating copy to clipboard operation
devrel copied to clipboard

Published 20 hours ago • verified publisher icon meilisearch

Our MVP: take everything but the doc out of the doc website

Open ferdi05 opened this issue 3 years ago • 21 comments

edited to reflect @dichotommy comments

The MVP for our resource center is quite easy to create: we can take everything that is not doc out of the documentation website.

So far, it would be:

  1. The full What is Meilisearch section - but the Telemetry and Search Preview pages
  2. The full Cookbooks section (including UGC)
  3. The FAQ section (possibly)

Summoning @dichotommy for validation, thanks!

ferdi05 avatar Feb 10 '22 16:02 ferdi05

Apologies for the delay in getting back to you on this!

  1. Yes, I believe you can take the full What is Meilisearch section. The only pages we may want to keep on the docs are Telemetry and Search Preview.
  2. No on this one: we should keep the Getting Started section in the docs. It's an expectation at this point that a docs site will have a getting started section and/or quick start. Putting this stuff in the resource center would just make it harder to find IMO.
  3. Yep, take 'em all 👌🏻
  4. Yes I think you could take the FAQ, I feel like I see these more often in resource centers than in docs sites.

The only additional candidate I can think of is the page on contributing to the docs. I'm unsure where the best place is for a contribution guide; it might actually make more sense in our repo README than on the docs site. In any case, let's hold off on making a decision about this one.

With the exception of the Getting Started, which we want to keep, your plan sounds good! Full speed ahead 🚂

dichotommy avatar Feb 21 '22 17:02 dichotommy

Thanks so much for your review Tommy. I'm happy to see that the plan is good so far. I'm ok to keep the Getting Started section in the documentation website, I did not notice that there was a 101 section. I'll add a direct link to the Quick start section in the navigation.

ferdi05 avatar Feb 21 '22 17:02 ferdi05

I did not notice that there was a 101 section.

We just added it today! 😁

I'll add a direct link to the Quick start section in the navigation.

That sounds great, thanks.

dichotommy avatar Feb 21 '22 17:02 dichotommy

Today I had a first meeting with @lpinot on the topic.

Before kicking off the project, I need to define precisely what would be the content that I'd like to see in the resource center, and what's that content type. For instance, a changelog is different from a blog post, the objects that are part of the content are very different.

Does this content need its own page, or is it a few blocks and then a link? For instance, we may not want to host the full changelog there, GitHub is suited for this. Same for the blog. So a preview of the last 3 blog posts could be enough, and then a link to the blog. But the comparison with our alternatives could be hosted there, and needs its own page.

We also discussed having a different UI when joining the homepage of the resource center, like a developer portal. For instance, Strapi resource center and Strapi website have a different UI. It's easier for developers to understand that they arrived in an area where the navigation will be different.

I should come up with some references of developer resource centers from other companies.

Some design research already exists on Figma.

i guess that i'll aldo do some reading on this.

After doing all this, we should be able to have a proper project kickoff meeting.

ferdi05 avatar May 04 '22 14:05 ferdi05

We could add the demos in the Ressource center

ferdi05 avatar May 17 '22 12:05 ferdi05

Let's try listing all the pages and their components here:

Page name Component 1 Component 2 Component 3
For all pages Internal navigation, Landing navigation (icon + text) Headers, section Text, links
For all pages Images, caption, gif Bullet points code styling
For all pages Edit this page
button		 anchors (internal linking) Callout
For all pages Content table Code samples, terminal Process steps (e.g.
https://docs.meilisearch.com/learn/cookbooks/gcp.html
)
What is Meilisearch/Overview N/A
What is Meilisearch/Features N/A
What is Meilisearch/Philosophy N/A
What is Meilisearch/Official SDKs, libraries Link to integrations: integration logo as a button Sections for integrations links
What is Meilisearch/Comparison to alternatives Tables Table content: ✅❌🔶 Alternatives' logo
What is Meilisearch/Language FAQ (question + answer)
What is Meilisearch/Contact us Contact form? (to be discussed)
Cookbooks/Run in Production N/A
Cookbooks/Use with Postman N/A
Cookbooks/Add a search bar to your docs N/A
Cookbooks/Set up HTTP/2 and SSL N/A
Cookbooks/Deployments Link to deployment guide: deployment guide as a button
Cookbooks/Deployment/AWS N/A
Cookbooks/Deployment/Azure One-click deploy button
Cookbooks/Deployment/GCP N/A
Cookbooks/Deployment/DigitalOcean N/A
Cookbooks/Deployment/Koyeb One-click deploy button
Cookbooks/Deployment/Qovery N/A
Cookbooks/Deployment/Railway One-click deploy button
FAQ FAQ (question + answer)

ferdi05 avatar Jun 20 '22 12:06 ferdi05

@lpinot @mdubus and @ferdi05 to kickoff this project on 2022-06-30

ferdi05 avatar Jun 21 '22 14:06 ferdi05

@dichotommy what do you think about the Migrating from Algolia section? Should it belong to the resources center or stay in the Documentation website? Thanks

ferdi05 avatar Jun 28 '22 09:06 ferdi05

Following our discussion with @ferdi05 and @lpinot here is the list of the content that we should have for the MVP:

  • What is Meilisearch
  • SDK list
  • Contact us
  • Cookbooks
  • FAQ
  • Migrating from Algolia (?)

In my point of view, the SDK list and the Contact us pages should be extracted from the What is Meilisearch section and put one level above, as these contain useful information that the user may want to retrieve quickly.



Here are some ideas of the links that we may want to have on the Resource Center (WDYT @ferdi05 @lpinot ?):

  • Documentation link*
  • Landing link
  • Github link(s)*
  • Blog link
  • Social Network links (Twitter, Linkedin, Youtube,…)
  • Link to the Slack Community
  • Link to the Roadmap

(*) The minimum links that should be part of the MVP from my point of view



And here are some pages that we may want to have someday:

  • Changelog
  • Demo page
  • Events page (Webinars, conferences like the Strapi one, …)

Here are some links that we could use for benchmark / inspiration:



@lpinot @ferdi05 don't hesitate to edit this comment to add some more information 👍

mdubus avatar Jun 30 '22 13:06 mdubus

2022-06-30 - Kickoff meeting with @lpinot @mdubus and @ferdi05

A few notes on what was discussed:

  • Morgane asked if the Resources Center is going to be part of the landing. It's going to be a dedicated app, possibly a subdomain. So it doesn't have to comply with the workflow of the landing.

  • Léna showed us some wireframes, all components previously discussed.

  • We discussed the navigation, but it's not easy to decide what it should look like. Having a top navigation menu, shortlinks to some pages on the left, and an internal menu of a page on the right, is obviously a lot.

  • We need to think about what are the other pages/components that we will add later to the Resources Center (started by Morgane). Some of the reasons why: SEO, make the right technology choice for this project.

  • We need to think about what the Resources Center homepage should look like.

  • We talked about marketing requirements: analytics (like Hotjar), and the possibility to have a hand to tweak pages easily.

  • Is the blog going to be part of the resources center? This is to be discussed. We need a blog because it's pretty much the only place to publish content at the moment. But there are different kind of content there: technical content (like tutorials), non-technical/product content (like why we chose open source), company-related content (like posts from the HR department). We may want to repost technical content in the Resources Center for instance.

  • What should be the name of the Resources center? A few ideas:

    • Dev center
    • Dev Resources Center
    • Dev Hub
    • Dev Portal

Portal sounds outdated. The word Developer should be included to make things clearer.

  • When will this be done? (here we mean the MVP) Morgane can tell when this will be done. She needs to know what would be the structure of the site and see the wireframes. This is needed to decide what is the easiest tech to use here, and then anticipate when could be the deadline.

TODO NEXT:

  • Define what are the missing pages and components that could become part of the Developer Hublater. Morgane started working on it, and this should be completed.

ferdi05 avatar Jun 30 '22 15:06 ferdi05

Regarding the order of importance in the Developer Hub, let's keep in mind what developers really want to see:

  1. Documentation and sample codes
  2. Tutorials and how-to videos
  3. Development tools, integrations & libraries
  4. Training courses and hands-on labs
  5. Technical support
  6. Answers in public forums (e.g. Stack Overflows)
  7. Community

All parts of the Developer Hub that I think we should have at some point (with some order, which can be discussed):

  • What is Meilisearch

    • Philosophy
    • Overview
    • Features
    • Languages

  • Documentation (external link)

    • Guides (external link)
      • Quick Start (external link)
      • Meilisearch 101 (Main features) (external link)
    • Reference (external link)
    • Core concepts (external link)
    • Security and permissions (external link)
    • Advanced topics (external link)

  • Cookbooks

    • Run in production
    • Deployment
      • AWS
      • Azure
      • GCP
      • DigitalOcean
      • Koyeb
      • Railway
    • Use with Postman
    • Set up HTTP/2 and SSL

  • Official SDKs and their documentation

  • Other Libraries

  • Tutorials (written and videos)

    • Integrate a relevant search bar to your documentation
    • from the blog: Instant-search, Gatsby,...

  • Demos

  • Technical blog

  • Sandbox

  • Training

    • Workshops
    • Academy

  • How to speak to us

    • GitHub
    • Slack
    • Twitter
    • Linkedin
    • Technical support

  • Newsletter

  • Use cases

  • Comparison to alternatives

  • Migration

    • From Algolia
    • From Elasticsearch

  • Roadmap (external link)

  • Versionning

    • Release notes (from the blog)
    • Changelog

  • Events

    • Where to find us
    • Previous events/talks

  • Local communities

  • Awesome-meilisearch

  • Contribution guide

    • Meilisearch
    • Integrations
    • Charabia
    • Documentation

  • Ambassador program

  • FAQ

  • Status

    • Cloud service
    • Meilisearch websites

  • Terms

    • Terms of Use/Service
    • Code of Conduct

  • Algolia migration guide

Also we will need a Meilisearch searchbar!

ferdi05 avatar Jul 11 '22 12:07 ferdi05

A benchmark was made, here is its link

mdubus avatar Jul 18 '22 05:07 mdubus

The benchmark is really cool. Some interesting findings. What would be the next step according to you @mdubus @lpinot ?

ferdi05 avatar Jul 18 '22 12:07 ferdi05

@mdubus @lpinot @chayaline I just discussed with @qdequele and he convinced me to consider i18n as soon as possible! It turns out to be really good for SEO!

ferdi05 avatar Jul 18 '22 15:07 ferdi05

i18n is great 🙌🏻 We had a chat with Léna about all the things we want to put in the dev center/hub, and we think it would be useful to prepare a survey to send to both internal and external users (through slack community maybe? or a tweet?). It will help us define clear information architecture as well as priorities on our user's side. On the design side, it will help us a lot to define a good navigation system and build the design around it.

Here is what we thought to ask:

  • sort the items Ferdinand listed in those categories: "very useful" "somewhat useful" "not useful" => this will show us what to implement first and in a prominent place
  • sort the items in groups (I still have to define how to ask this and if we propose premade groups or not) => this will give us an indication of the navigation style and possible categories. Having clearly defined categories would help our users not get lost in the amount of content available, and quickly find what they need.
  • do you prefer the documentation to be integrated to the dev center or a dedicated documentation site? (we will show examples)
  • open questions to ask them what they expect the most from this hub, and another free answer to let them express any feedback or need.

If we combine the results from this survey with our internal needs on the tech and devrel sides we can have a clear direction and build something solid.

WDYT about it? are there any questions you would like to ask?

chayaline avatar Jul 19 '22 11:07 chayaline

Hi 👋

@ferdi05 Lena and Charline are working on a survey to determine the user's expectations. This could also help us decide whether we should integrate the documentation inside the Resource Center or not.

On my side, I'm also having a discussion with Tommy to know his point of view on this, and I'm trying to determine the technical complexity of having the documentation inside the Resource Center, and I can tell that it wouldn't be a piece of cake 🤭 I've also started to check the different tools we could use to develop the Resource Center. I've already crossed out Tailwind's Syntax Template as their Licence wouldn't allow us to build an end-product and make it Open-Source.

Regarding the survey, we will probably have a call together in the next few days to take a look at it together and make sure it reflects the questions we have. It will definitively be helpful 🙌

mdubus avatar Jul 20 '22 10:07 mdubus

Hello all!

@dichotommy what do you think about the Migrating from Algolia section? Should it belong to the resources center or stay in the Documentation website? Thanks

@ferdi05 I think it makes the most sense in the resource center / developer hub.

It's a bit tricky to define which articles belong in the resource center and which ones belong in the docs. To summarize my gut feeling:

  • If the main focus of the article is the behavior or usage of Meilisearch, it belongs in the docs
  • If the main focus of the article is integration with an external tool, it belongs in the resource center (e.g. Deploy guides, cookbooks)
  • If the main focus of the article is understanding Meilisearch as a company or a product, it belongs in the resource center (e.g. Contact us, SDKs list, comparison to alternatives)

We still need to discuss ownership of the pages in the resource center. Who will be responsible for keeping them up to date? I know that we do not feel very qualified to do so on the @meilisearch/docs-team, since in most cases we did not write the articles ourselves and lack familiarity with the external tools being described.

Some of the articles we've discussed using for the MVP already have specific maintainers today, like the Cloud deploy guides which are updated periodically by members of @meilisearch/integration-team . Others are in a more "abandoned" state without anyone specific looking after them.

dichotommy avatar Jul 25 '22 15:07 dichotommy

@chayaline @lpinot @mdubus @ferdi05 met on 2022-08-08 to discuss findings from the Maze survey. The first results are in:

We are going to use the Developer Hub private repo to gather our efforts.

ferdi05 avatar Aug 09 '22 07:08 ferdi05

@lpinot @mdubus and @ferdi05 met on 2022-09-19 to discuss the project progress. Minutes are on Notion (private link)

ferdi05 avatar Sep 19 '22 14:09 ferdi05

Will be handled by our web agency

ferdi05 avatar Jan 12 '23 16:01 ferdi05

Some of the articles we've discussed using for the MVP already have specific maintainers today, like the Cloud deploy guides which are updated periodically by members of @meilisearch/integration-team. Others are in a more "abandoned" state without anyone specific looking after them.

(first of all, sorry because this notification flown away of my radar)

Hi @dichotommy, as far as I know, we only update the GCP cookbook periodically.

CC: @ferdi05

brunoocasali avatar Jan 16 '23 16:01 brunoocasali