search

gentics / mesh

Gentics Mesh - The open source headless CMS for developers
https://getmesh.io
Apache License 2.0
572 stars 115 forks source link

Enhance getting started guide #937

Open erinfry6 opened 4 years ago

erinfry6 commented 4 years ago

I'm interested in using Gentics Mesh, but the documentation around getting started and demoing the tool is sparse. A step-by-step demo of content creation would be extremely useful! If one already exists, it is difficult to find. Where is it?

Thank you!

Edit: Typo

Jotschi commented 4 years ago

@erinfry6 Unfortunately I think this topic is not covered very well. We have however a react guide which covers content modelling and content setup.

https://getmesh.io/docs/guides/mesh-react/

Maybe this guide will help you.

Jotschi commented 4 years ago

@erinfry6 If you have suggestions on how we could improve our getting started guide please let me know. I'm curious what you think should be included as first steps. I always had the impression that content creation (schema setup and adding of contents) was self explanatory. But I now think a quick video / guide that shows the basics could really help.

erinfry6 commented 4 years ago

@Jotschi, Thank you for the quick response! I do not think that the node, schema, content concepts are self explanatory at all, actually. A well done step-by-step tutorial could solve this though. I would add defining and understanding those concepts into your tutorial.

Regarding the link, unfortunately I tried to follow it and at almost every step it was either lacking information to follow the instruction, or simply didn't work. It would behoove you to ask someone not involved in the project to walk through it with you. Here are some pieces of feedback for you to start:

Step 1: I tried cloning and I get an error saying I cannot clone this repository. That's fine, maybe it's my machine. So I go to the github and download the repo. I then compare the code for Navigation.jsx to what I just downloaded ... its nothing alike. There are no instructions about if I'm supposed to change the existing code or not.

Step 2: I arrive at Step 2. It seems completely disjointed, it seems like Step 1 wasn't necessary after all... I try starting from scratch (the first line).

Step 3: You do not describe where the JSON Editor is! I started a Docker container from code not on my machine, all I have is the web browser interface and there is no instruction about entering the JSON editor. Maybe I should know, I try googling and don't find anything. So I give up. I choose to use the second Docker code from Step 2.

Step 4: I create a new project, and go to associate Project Schemas with the project. I click on the schemas and a green box pops up "Project assigned" but the box does not become a check! Maybe this is bug you're fixing.. but on top of everything else at this point I do not want to continue.

Alas, I do and I get to the Step 4 Space Shuttle Vehicle section. The interface throughout is different than the screenshots, but I could figure it out. At least I could until I add the Vehicle Image. 'SELECT NODE REFERENCE' and the screenshot that pops up is not a list of images, but rather a list with only the Space Shuttle I am editing.. and I cannot choose anything.

One of the strengths of Gentics Mesh is that you do have pretty clear documentation about adding and modifying the content model thru code (not necessarily through the interface). I think it has a lot of potential, but the lack of followable introductory material makes it very difficult to understand the tool.

Jotschi commented 4 years ago

@erinfry6 Thank you for the detailed feedback.

We have recently (with release 1.0) updated the UI and thus some screenshots still show the old UI. I'll rework the example screenshots to keep things consistent.

I think a step by step guide which explains the basic concepts is really something we need. It would help the users to grasps the basics of what mesh consists of and how to use each component. When writing those guides and posts it is really difficult to put yourself in the seat of the reader. Your feedback certainly helped to get a better view on what aspects are often overlooked.

I tried to explain most of the concepts of Mesh in this post which is actually not technology specific. The post however does not cover UI basics.

I think I'll add content modeling and creation to the article or add a dedicated page for this.

Lastly I want to mention that we also have very basic and easy to follow guide in the gatsby docs. https://www.gatsbyjs.org/docs/sourcing-from-gentics-mesh/

It however also does not contain information about content creation and modelling.