Feedback on Developer Documentation


#1

Hi everyone,

I’m about to start working on re-writing out documentation platform so everyone can learn Grakn much faster and deeper. Does anyone have any feedback or ideas that they would like to highlight to my attention for us to consider adding to the documentation?

Thank you, everyone! Would love to hear your thoughts!


#2
  1. it would be really helpful if you could SEO optimize the documentation. Right now it is very hard to query the doc via Google. It only works for a crew keywords

  2. I was lucky enough to listen to one of your keynotes, so I understand your previous nomenclature. Some old terms (eg the name that attributes where called before) are still in there and will certainly confuse readers.

  3. GRAQL should be explained in more detail. Some keywords could use more examples and not everything is covered there. Eg “aggregate group $x count”.

‘val =’ should also be given an example. It’s implicitly covered, but I had to try in the console to make sure it worked as I guessed.

I think ‘via’ could be documented more clearly.

In general, the whole documentation on ‘match’ could be expanded a bit.


#3

The documentation has focused (rightly) on fundamentals of knowledge graphs and ontologies; how to define them and use them for productive efforts. It is functional and commendable, though descriptions of what to do in certain edge-cases and the finer points of syntax could be expanded upon. Practice with the software meets a lot of those needs.

Where the documentation in its current state has fallen down for me is where it leads us immediately after we get excited about using it on our desktops. Having shown us all the cool stuff we can do, we are then confronted with the challenge of establishing lab systems or other persistent, production-like servers that can demonstrate this magic to colleagues, clients, and superiors.

Now I realize that, at a certain point, Grakn as a company must demonstrate the ability to generate revenue, and thus develop an unambiguous pathway from the world of free software into the licensed, paid, enterprise realm of the KGMS. However, the intermediate step here needs to be recognized and enabled so that we can point at our various knowledge-graphs, show the value they’re generating, and then ask for money so we can have more of the same, faster, with better control and assurance of security. At the moment, though, this transition from a development virtual-machine environment to something that lives in infrastructure is largely a guessing game.

It would be grand if there was more about what best practices and intended use-cases were for operating a performant medium-scale graph database. What do I need to do with Java when I want to store a million objects? What sort of replication strategy is most appropriate in a Cassandra cluster to optimize query performance? How do indexes in Grakn work, specifically? What are some gotchas to look out for when writing queries? What are some problems with scaling that people can expect to run into? What are the functions of the various tables in the Grakn cassandra data, and what can we expect if we run into problems?

The more useful you can make this system for real world applications the more likely it will be that people with money to spend will be directed your way.


#4

Thanks, @tomen !

it would be really helpful if you could SEO optimize the documentation. Right now it is very hard to query the doc via Google. It only works for a crew keywords

I’m not very familiar with SEO optimisation techniques, do you have any pointers as what we can do for our Docs?

[…] Some old terms (eg the name that attributes where called before) are still in there and will certainly confuse readers.

Do you know where in the Docs that this appears?

Every other point makes sense and I will make sure they get fixed, Tommi! Thank you so much!


#5

Thank you so much for the deep and insightful feedback @awaschick! You gave me lots of ideas not only to the docs, but also adoption strategies we can help our community. I will dissect your feedback into many pieces and add them to our roadmap. Thank you again!


#6

Thoughts on the documentation:

  • The integrated search is very limited. If I search for certain examples or keywords like “implicit”, the search doesn’t show any results.
  • Some things are only documented in the Academy, whilst others only in the Documentation. So I need to remember the location to recall information.
  • I had a hard time understanding the REST API chapter. A hands-on example here would be helpful.
  • A documentation for the Node.js driver would be great. With a tutorial e.g. on how to build a chat-bot using express, socket, etc.

#7

I’d like to see more python related examples, tips & tricks for beginners.


#8

I’m not very familiar with SEO optimisation techniques, do you have any pointers as what we can do for our Docs?

Basically in this context: Use the key terms you want to be found on via Google in the H1 (use only one H1), use secondary terms in H2.

Examples: Instead of “Defining Schema”, use “Grakn Schema”.

It is possible that the H1 is not the biggest text in the doc, so for users it does not have to be the thing that appears as the title. You can make it like a headline above the actual headline that is a bit smaller. Thereby, you can keep fancy titles for end users and still tell Google what the main purpose of this article is about.

Example:

Grakn Schema
Building Schema: This is how you define fancy titles in Grakn

Do you know where in the Docs that this appears?

I’ve looked around a bit but can’t find it. If I stumble across it, I will let you know.