Details

      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!

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

        Activity

        Hide
        kzeller kzeller added a comment - - edited

        Hi Perry,

        I'm starting to integrate these comments into the content. Be very aware that there are a few I cannot address due to conventions and constraints in our system. After I am done with the content/changeable comments, I will close this ticket. Below are the issues I will close out without resolving because they are dependent on our production system and conventions built into the system:

        -True, would require restyling for whole site and therefore deferring. So basically links and any items tagged for emphasis, including terms, are bolded. : " 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? "

        --Also a system-wide change: 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?

        --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?

        --Putting each section into its own chapter: Forces us to use these mandatory tags in this hierarchy in order to parse as valid XML:
        -Chapter then title, then at least one section.

        So you cannot have a standalone chapter that is just "Installation" with all the information and no subsection. Now that as we have discussed in the past, is not-so-great form for print or web, however I've done my best with the constraints to consolidate into chapters containing 2 sections.

        Show
        kzeller kzeller added a comment - - edited Hi Perry, I'm starting to integrate these comments into the content. Be very aware that there are a few I cannot address due to conventions and constraints in our system. After I am done with the content/changeable comments, I will close this ticket. Below are the issues I will close out without resolving because they are dependent on our production system and conventions built into the system: -True, would require restyling for whole site and therefore deferring. So basically links and any items tagged for emphasis, including terms, are bolded. : " 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? " --Also a system-wide change: 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? --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? --Putting each section into its own chapter: Forces us to use these mandatory tags in this hierarchy in order to parse as valid XML: -Chapter then title, then at least one section. So you cannot have a standalone chapter that is just "Installation" with all the information and no subsection. Now that as we have discussed in the past, is not-so-great form for print or web, however I've done my best with the constraints to consolidate into chapters containing 2 sections.
        Hide
        kzeller kzeller added a comment -

        Here are the docs-related fixed, or if they have to do with our publishing system conventions/constraints, won't-fix:

        [WON'T FIX: Convention of System]-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?
        [WON'T FIX: Convention of System]-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?

        [WON'T FIX: Convention of System]-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?

        [Fixed with different section breakdown]-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.
        [Fixed]-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..."
        [Fixed]-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.
        [Added install cross ref]-http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-prerequisites.html: Link the beer-sample requirement to show the user how to install it?
        [added cross ref] -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
        [Fixed]-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"
        [Added to step]-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.
        [REWROTE to reflect what is stored in ES]-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...
        [made smaller]-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

        [REWROTE and RENAME]-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.
        [FIX]-http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-debugging.html - Typo: "For production systems the log find is at"

        [OPEN REQUEST]-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.

        [MOVE FOR PROMINENCE AND CROSS REF]-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?
        [FIX]-http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-index-fail.html - Typo: "try the checking the following"
        [FIX]-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
        [REWROTE, MOVE AND RENAME]-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

        Show
        kzeller kzeller added a comment - Here are the docs-related fixed, or if they have to do with our publishing system conventions/constraints, won't-fix: [WON'T FIX: Convention of System] -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? [WON'T FIX: Convention of System] -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? [WON'T FIX: Convention of System] - 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? [Fixed with different section breakdown] -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. [Fixed] - 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..." [Fixed] - 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. [Added install cross ref] - http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-prerequisites.html: Link the beer-sample requirement to show the user how to install it? [added cross ref] - 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 [Fixed] - 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" [Added to step] - 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. [REWROTE to reflect what is stored in ES] - 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... [made smaller] - 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 [REWROTE and RENAME] - 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. [FIX] - http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-debugging.html - Typo: "For production systems the log find is at" [OPEN REQUEST] - 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. [MOVE FOR PROMINENCE AND CROSS REF] - 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? [FIX] - http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-index-fail.html - Typo: "try the checking the following" [FIX] - 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 [REWROTE, MOVE AND RENAME] - 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
        Hide
        kzeller kzeller added a comment -

        Hi Marty,

        here is an open item from reviews of this document:

        [OPEN REQUEST]-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.

        So we need clarification: Will ES have the same number of items, sort of the same number or what? When I ran it on my computer it was the same number, but I know there are also checkpoint docs so it may be more.

        What is the word on this when we suggest people compare number of documents as a way to troubleshoot?

        Let me know and assign back for me to doc.

        Show
        kzeller kzeller added a comment - Hi Marty, here is an open item from reviews of this document: [OPEN REQUEST] - 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. So we need clarification: Will ES have the same number of items, sort of the same number or what? When I ran it on my computer it was the same number, but I know there are also checkpoint docs so it may be more. What is the word on this when we suggest people compare number of documents as a way to troubleshoot? Let me know and assign back for me to doc.
        Hide
        mschoch Marty Schoch added a comment -

        To me the documentation is correct. The confusing part is, the document counts SHOULD match IF you count correctly.

        The document at:

        http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-debugging.html

        teaches users how to count correctly. When you count correctly, the numbers should match (provided things are not changing on the source side).

        The document at:

        http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-indexing.html

        Warns users that the document counts will not match. And this because the count shown in the UI is different (it is the count of all documents in the index, which includes the checkpoint documents). This UI is not our code, so we cannot simply change it to show a different value.

        So, I would say that technically both pieces of documentation are correct, but the reasons are subtle and could confuse users. However, I don't really have any good suggestions on how to change it.

        Show
        mschoch Marty Schoch added a comment - To me the documentation is correct. The confusing part is, the document counts SHOULD match IF you count correctly. The document at: http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-debugging.html teaches users how to count correctly. When you count correctly, the numbers should match (provided things are not changing on the source side). The document at: http://www.couchbase.com/docs/couchbase-elasticsearch/couchbase-elastic-indexing.html Warns users that the document counts will not match. And this because the count shown in the UI is different (it is the count of all documents in the index, which includes the checkpoint documents). This UI is not our code, so we cannot simply change it to show a different value. So, I would say that technically both pieces of documentation are correct, but the reasons are subtle and could confuse users. However, I don't really have any good suggestions on how to change it.
        Hide
        kzeller kzeller added a comment -

        Resolved. For the last item I added this based on Marty's clarification:

        -----------

        Note that the number of documents displayed by Elasticsearch head may be greater than the actual number of documents in Couchbase Server. This is because XDCR and the Couchbase Plug-in for Elasticsearch will also send additional documents that describe the status of replication and Elasticsearch head will show this total number. There is an alternate, more accurate way you can determine the true number of documents indexed by Elasticsearch, which excludes extra status documents. You can use this method to debug possible data transfer issues between Couchbase and Elasticsearch. For more information, see , Compare Document Count.

        Where the last sentence is a linked reference to the right approach.

        Show
        kzeller kzeller added a comment - Resolved. For the last item I added this based on Marty's clarification: ----------- Note that the number of documents displayed by Elasticsearch head may be greater than the actual number of documents in Couchbase Server. This is because XDCR and the Couchbase Plug-in for Elasticsearch will also send additional documents that describe the status of replication and Elasticsearch head will show this total number. There is an alternate, more accurate way you can determine the true number of documents indexed by Elasticsearch, which excludes extra status documents. You can use this method to debug possible data transfer issues between Couchbase and Elasticsearch. For more information, see , Compare Document Count. Where the last sentence is a linked reference to the right approach.
        Hide
        kzeller kzeller added a comment -

        Resolved. For the last item I added this based on Marty's clarification:

        -----------

        Note that the number of documents displayed by Elasticsearch head may be greater than the actual number of documents in Couchbase Server. This is because XDCR and the Couchbase Plug-in for Elasticsearch will also send additional documents that describe the status of replication and Elasticsearch head will show this total number. There is an alternate, more accurate way you can determine the true number of documents indexed by Elasticsearch, which excludes extra status documents. You can use this method to debug possible data transfer issues between Couchbase and Elasticsearch. For more information, see , Compare Document Count.

        Where the last sentence is a linked reference to the right approach.

        Show
        kzeller kzeller added a comment - Resolved. For the last item I added this based on Marty's clarification: ----------- Note that the number of documents displayed by Elasticsearch head may be greater than the actual number of documents in Couchbase Server. This is because XDCR and the Couchbase Plug-in for Elasticsearch will also send additional documents that describe the status of replication and Elasticsearch head will show this total number. There is an alternate, more accurate way you can determine the true number of documents indexed by Elasticsearch, which excludes extra status documents. You can use this method to debug possible data transfer issues between Couchbase and Elasticsearch. For more information, see , Compare Document Count. Where the last sentence is a linked reference to the right approach.

          People

          • Assignee:
            kzeller kzeller
            Reporter:
            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