[
https://issues.apache.org/jira/browse/HBASE-12902?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14292437#comment-14292437
]
Misty Stanley-Jones commented on HBASE-12902:
---------------------------------------------
[~larsgeorge] The current structure actually reflects a big usability win for
readers (IMHO), since it exposes more information they are likely to be looking
for, with only a single click or Ctrl+F. It also allows people to "learn" the
structure of the book, and exposes current layout issues, such as half of the
book occurring after the Appendixes start. Anecdotally, we have had very
positive feedback on the new layout, with very little negative feedback indeed.
I actually think that we should remove *all* of the numbering, continue to
expose the top-level sections within "chapters", and additionally add the
ability to permalink to each top-level section in the book. I chose to remove
the numbering from the chapters because they are way bigger than chapters
should be, and should more properly be called Parts. The chunking in the book
is all wrong.
Permalinks, along with quick-links to report bugs against a given section,
would make reporting problems easier and less error-prone. Using numbers as
though it were a printed book makes bugs harder to find and fix, and reduces
the archival value of searching reported and fixed/notfixed bugs over time.
As far as the structure in general, it won't get a rework (by me) until the v2
book is started. There are too many other things that need doing. Patches
accepted, of course.
> Post-asciidoc conversion fix-ups
> --------------------------------
>
> Key: HBASE-12902
> URL: https://issues.apache.org/jira/browse/HBASE-12902
> Project: HBase
> Issue Type: Bug
> Components: documentation
> Reporter: Misty Stanley-Jones
> Assignee: Misty Stanley-Jones
> Fix For: 2.0.0
>
> Attachments: HBASE-12902.patch
>
>
> - Put HBase logo back on book
> - Remove docbkx building instructions and make sure asciidoc building
> instructions are solid
> - Several feedback items from [~larsgeorge]:
> {quote}
> Lars George
> Jan-19 8:45 pm
> @misty Something is off with Table1, no?
> https://github.com/apache/hbase/blob/master/src/main/asciidoc/_chapters/getting_started.adoc#24-adva...
> Lars George
> Jan-19 8:45 pm
> Is seems like a header for a table, but has no content
> Misty Stanley-Jones
> Jan-19 8:47 pm
> yes you are right
> Lars George
> Jan-19 8:47 pm
> @misty yeah, it is missing the node-a etc in the first column and the Xs (I
> presume) in the others for the assignment
> {quote}
> {quote}
> Lars George
> Jan-19 11:53 pm
> @misty 2.4 (or was it 2.3, but it is at the end of that section) and 5. are
> messing up the ports for the UIs
> Lars George
> Jan-19 11:56 pm
> @misty there is a stray section between 2.5 and 3. that seems lost and out of
> place.
> Tuesday January 20, 2015
> Lars George
> Jan-20 12:04 am
> @misty hbase.balancer.period in the section with the parsed hbase-default.xml
> is borked
> Lars George
> Jan-20 12:05 am
> A few more below that are also borked
> Lars George
> Jan-20 12:15 am
> This is 6.2 btw
> Lars George
> Jan-20 12:16 am
> There are quite a few where "Description" is missing and the actual
> description is printed as Courier font text, like the property name
> Lars George
> Jan-20 12:17 am
> @misty That dangling section between 2.5 and 3. seems redundant, as 6.x
> explain them all. Unless the former is for the quickstart section?
> Lars George
> Jan-20 12:41 am
> @misty 11.1 also stuffs up the ports, the new master port in this case
> Lars George
> Jan-20 12:43 am
> @misty in general the upgrading sections should be subsections (11, 12, 13,
> etc should be no major sections)
> Lars George
> Jan-20 12:45 am
> @misty between 17. and 18. is another dangling section with no numbering
> Lars George
> Jan-20 12:47 am
> And again, 18., 19., 20. etc should be one major section with subsections,
> not all major section on their own
> Lars George
> Jan-20 12:47 am
> I presume now that that dangling section between 17. and 18. is the Intro and
> the other should be beneath it. I guess also then this is the same for
> earlier issues with section placements.
> Lars George
> Jan-20 12:51 am
> Yeah, same for 23.5 to 24., the Data Model is the intro but shows up dangling
> and all else is moved up the hierarchy
> Lars George
> Jan-20 1:19 am
> @misty 38. (or whatever that really is now that I noticed the broken
> hierarchy) is also out of date.
> Lars George
> Jan-20 1:20 am
> (well decoupled flushing is still being worked on though)
> {quote}
> {quote}
> Lars George
> Jan-20 8:05 pm
> @misty 70.5 the lead into the bulleted list is borked, it appears as part of
> the first item
> Lars George
> Jan-20 8:06 pm
> @misty and did you see those other 20+ message I sent earlier? Just checking
> you se them
> Lars George
> Jan-20 8:08 pm
> oh, and a spell check run would not be the worst idea. Some later content is
> off.
> Lars George
> Jan-20 8:27 pm
> @misty Same issue with bulleted list in 70.7.7 - I assume this is a wider
> issue after conversion?
> Lars George
> Jan-20 8:39 pm
> @misty "Parameters Used by Compaction Algorithm" the table is broken
> {quote}
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
