Uploaded image for project: 'Couchbase Server'
  1. Couchbase Server
  2. MB-7723

Docs: Elastic Search review

    XMLWordPrintable

Details

    • Improvement
    • Resolution: Fixed
    • Major
    • None
    • 2.0
    • None
    • Security Level: Public
    • None

    Description

      Hey Karen, nice job putting this altogether. My comments:

      -General convention note that I noticed...some terms are bolded, but look gray and get confused in my mind with links. For example, this page http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-configurations.html, has the word "index" in bold in the first paragraph but it looks like a link. I imagine this is across all our documentation, could you work on tweaking that a bit to make it clearer the difference between links and bold?
      -Another one: The "Prev" and "Next" links at the bottom of the page are good, but I keep trying to click on the actual title of the previous/next chapter...could we make that part of the link as well?

      -http://www.couchbase.com/docs/couchbase-elasticsearch/index.html: The list of figures looks quite bold, seems to call out for some reason. Maybe we can make that fit in beter with the rest of the page?
      -Is it also not a little odd that we only have one chapter with multiple sections below? Just seems a little strange. Maybe you could put the text of this page (http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic.html) on the main page and then just have each child section be it's own chapter. That would reduce some of the empty whitespace of the landing page.
      -http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic.html - Typo after last code sample: "With Elasticsearch you can use text search queries can provide logic..."
      -http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic.html - At the end, I would suggest at least a paragraph break after "regular expressions to express criterion.". I would also suggest that we may want to move the rest of this to either the front page and/or higher up in the text to give the users these resources ahead of time rather than making them scroll down to the bottom of the page.
      -http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-prerequisites.html: Link the beer-sample requirement to show the user how to install it?
      -http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-plugin-install.html: I would suggest linking to the Elastic Search documentation more explicitly for installation instructions, and raising the visibility/level of the last line on the page
      -http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-indexing.html: I think you want "docs" at the end of the page: "The doc : field"
      -http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-indexing.html: Call out specifically that the Elastic Search plugin is listening on port 9091 as that is a non-standard port for Couchbase users and may lead to some confusion. Not sure if this page is exactly the right place, might be better to put it in the installation but I'm not sure.
      -http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-querying.html: I think this is a little confusing: "Notice that source attribute will contain only metadata from Couchbase Server,"...it implies that Couchbase Server is only sending metadata and you don't have the whole document available. Not sure how to rewrite...
      -http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-modeling.html: I'd suggest making the first two images a little smaller, they seem to dominate the page and overwhelm the text a bit
      -http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-modeling.html: I think this page is a little confusing the way it is laid out. The first 5 paragraphs don't actually discuss "how to model documents for elastic search" (as the title would imply) but rather focus on "what to do when your schema changes". It would also be good to link to this page (http://www.elasticsearch.org/guide/reference/mapping/) and add some text since this section implies that the user would never be able to change the mapping if they change their document structure (which isn't correct. In general, I think we could use a more introductory section providing guidance on how to model documents with elastic search, and then use the current page to detail some of the oddities that you should be aware of. If I come to this page, I expect to learn how to model documents...it doesn't really cover that.
      -http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-debugging.html - Typo: "For production systems the log find is at"
      -http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-debugging.html - We need to get some more clarification from engineering about the document counts in Elastic Search. This page says that they should be the same as in Couchbase, but this page (http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-indexing.html) says that there will be more in Elastic Search due to extra docs that Couchbase sends over. If both are correct, maybe a little clarification.
      -http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-debugging.html - Can you link the bottom bullet points to the sections that you are going to talk more about?
      -http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-index-fail.html - Typo: "try the checking the following"
      -http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-performance-mgmt.html - Some other performance improvements would be to add more Couchbase nodes, or look to use SSD's for the data directory which allows us to read and write data from disk much faster
      -http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-performance-mgmt.html - The bottom of this page "Understanding Performance Changes in Practice" doesn't really match the text to the title. The text is useful, but is all about concurrent connections and replications and doesn't really cover the general concept of Understanding Performance Changes. I might also suggest that the monitoring/troubleshooting section is very closely related to this performance section and the two "could" be combined.

      Nice job!

      Attachments

        No reviews matched the request. Check your Options in the drop-down menu of this sections header.

        Activity

          People

            kzeller kzeller
            perry Perry Krug
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

            Dates

              Created:
              Updated:
              Resolved:

              Gerrit Reviews

                There are no open Gerrit changes

                PagerDuty