search

yugabyte / yugabyte-db

YugabyteDB - the cloud native distributed SQL database for mission-critical applications.
https://www.yugabyte.com
Other
8.87k stars 1.05k forks source link

Documentation #3832

Closed andymans closed 4 years ago

andymans commented 4 years ago

Please have a look at the website of someone who does documentation well, and learn. To say that your documentation sucks is to massively under-state how utterly abysmal it is.

stevebang commented 4 years ago

@andymans Thanks for taking the time to share your frustration. The YugabyteDB documentation is a work in progress, with initial documentation done by developers. I was hired recently to improve the documentation. We'd appreciate your thoughts on the following questions related to your experience:

  1. Please give a few specifics about what you looked for and didn't find?

  2. What did you find that was frustratingly lacking in clarity, accuracy, or coherence?

  3. Please share a site that you enjoy using the documentation.

Thanks!

andymans commented 4 years ago

Hi Steve,

Excellent news that you are on board! I'm delighted to hear it. Here are my two cents:

  1. The 'Marketing" site is a different animal from the documentation site. While it's appropriate to have a 'Documentation Lite" part of the Marketing site (at-a-glance-features, yugabyte-101, architecture overview etc) it's a poor idea to try and weave 'implementer-level' docs within what is still a 'Marketing Process' - too high level, and the implementer feels short-changed; too low-level and the prospective 'customer' feels baffled-by-science.
  2. The format of the implementer level docs needs to be as simple as possible. A left hand side bar with navigation, and scrollable content on the right-hand 2/3 of the page. Nothing fancy. Nobody ever complained that something was too simple for them! The CSS-heavy, box-shadowed 'panels' that are currently the default interaction style with the docs do NOTHING to aid my understanding of the content; in fact they IMPEDE it. As an implementer I know "what" I want to read - just show me a link in the navigation that allows me to find it....then present it to me like I was 10 yrs old (as clear and simple as possible).
  3. This is a BIGGIE - the docs for the 4 separate products (SQL Db, DOC Db, Graph Db, and Yedis) are all muddled together. I'm halfway through reading about some topic that 'seems' as if it's talking about the YSQL features before I find out that this is in fact a YCQL doc. This is a massive No-No!! It's surely essential that the documentation maintains a clear separation here. I can see how this happened; but it needs fixing. Yes there are parts of the documentation that are 'generic' or 'yugabyte platform level' but the bulk of 'how to do xyz' will be specific to the technology being used - either the SQL, the Document store, or whatever. If I select to enter the 'Doc Store' guide, I definitely do not want to see anything in there telling me how to create an SQL table :-) It may be appropriate to Structure the Guide according to Developer Journeys. What does a developer do? INITIAL JOURNEY: a) Downloads and Installs the platform b) Wonders OK how do I get started with working with data storage prodcts c) Answer: I might start by "modelling my data" d) How do I do that if I'm using YCQL, YSQL, Yedis e) Finds the right set of documents, maybe with some examples, and links to github projects showing how simple data modelling and insertion/manipulation of data happens in the "relevant" part of the platform INTERMEDIATE JOURNEY: a) Now that I'm familiar with the basics of Yugabyte, I need to have at hand a Reference Guide b) I don't want to be sold to (I already have the product by this point) I just want hard technical info c) I want step-by-step instructions for common tasks - because that is the way I tend to work - I put on my pants first, and my shoes last in order to achieve the result "leave the house properly dressed" - so what do I need to do to achieve the result "yugabyte database running in multiple data centers with European customers in one data center, Asian customers on another"? d) During these tasks, I will get stuck - I will, for example forget what are the available data-types I can use in the SQL product. So I'll be needing a technical reference Manual. e) Pictures are worth a thousand words - but they must be well drawn! Standardize on a Diagramming convention and style throughout the docs. It's not only professional, but practical - I want to feel I'm speaking to the same 'person' right through my documentation journey. ADVANCED JOURNEY: a) OK - thanks to the excellent docs and tutorials and well-organized code-samples, I hav emanaged to swiftly build something I'm proud of. Now I want to show it to the world!! b) So I need deployment guides c) But my deployment options are many. So what I do NOT need is to have the deployment guides confusing me:-) If I'm deploying to AWS, or Digital Ocean - I want to guided for that "specific" deployment ONLY. If that deployment can be 'scripted' (automated) then any git hub repos containing scripts, pre-built Docker images will be greatly appreciated. This is the kind of 'needs anticipation' that endears a supplier to their customer. ONGOING JOURNEY a) Ok I've deployed my Yugabyte system. I might think that's then 'end' of the story; but I'd be wrong. b) It's just the beginning. I'm now into maintenance, monitoring, and upgrading the system, and I'm going to need more help with all of these topics. c) But it's OK - because I know a guy (Steve) who's on the case!!

Good (or at least in my opinion) Products that make it easy for developers to be productive:

RethinkDb - their documentation is pretty good (especially considering it was all done on a shoestring budget) - clear topics (that developers need to know about) well presented, and excellent use of examples to help clarify a point when needed.

CockroachDb - their docs are "fairly" good - again simple presentation of the content is where they win. There is room for improvement there - but they present a clear selection of topics which makes a large swathe of navigation problems disappear.

Apple Final Cut Pro - not an example of "what it should look like" but an example of how well they have understood the needs of their developers - if you look at how Apple guides the user to the information that they need to be successful with their product the amount of effort that they spent "understanding" their users' needs become apparent. They navigation choices, and the presentation of info in each section are quite excellent. But they do of course have almost unlimited budget. Nevertheless some good inspiration can be gained for free!

stevebang commented 4 years ago

@andymans Thanks for your feedback! The docs are getting lots of attention now, and you should see incremental improvements as Yugabyte grows. I'm curious what use case brought you to check out YugabyteDB. That helps us calibrate areas to focus on in the docs.