CUBRID Online Manual XE Docs improvements

2011-04-06
2013-06-05
  • Esen Sagynov
    Esen Sagynov
    2011-04-06

    Dear Catalin,

    I have noticed that you haven't implemented one feature that I requested. In the left TOC I asked to display sibling nodes for the currently opened page. At this moment when you click on the node it expands it, if there are children nodes, and hides all the rest sibling nodes. I have sent an email in one of the XE Docs revisions. So, please fix this to show sibling nodes, too. I have already got a feedback from an external user who participated in the Quizland event. Here is what that slapo users says:

    "I've also noticed the manual got a different look yesterday or the day before. Looks good to me, except for one thing - when I choose an item, say, "Overview" in section "CUBRID System Catalog", the it's the only item in the side menu. I think it would, however, be much nicer if it would be just highlighted among the items of the same level, which could then be visible. Could you pass this feedback to the people who work on the online documentation browser?"

    Esen.

     
  • Esen Sagynov
    Esen Sagynov
    2011-04-06

    Esen: Just to add to my previous message: the TOC on the left is the same as the breadcrumbs. So one of them is redundant. That's why this is another motivation to change the structure of the left TOC.

    ==================================================================

    Dear Esen,

    The current TOC behavior is the one that is currently used on MSDN.
    Regarding TOC and breadcrumbs is not quite the same thing (redundant) because breadcrumbs have no available children nodes (at least in my opinion).
    I understand what the user says but I am not sure that all the users have the same opinion about this. Please allow me to get some more feedback about the current TOC (or the possibility to change it like you said) from other users as well before making any changes. I will get back to you on this issue.

    Best regards,
    Catalin Ciobanu

    ==================================================================

    Dear Catalin,

    I have noticed this issue at the very beginning and asked to change it. At that moment MSDN was almost the most convenient manual system, however, not the ideal. In the current manual, I ALWAYS have to navigate back to the parent node to see what other contents are available for the page I was reading. Except the previous and next articles I cannot know others. The current TOC is the same as the breadcrumbs when you are reading the leaf node. So it is very inconvenient for me. I do not know how you use. So, if you do not have serious reasons not to fix this, please change the default behavior.

    Thanks.

    Esen.

    ==================================================================

    Hi.

    Maybe comparing MSDN with CUBRID Manual is a little bit out-of-line:
    - Some of the most useful parts: "Related sections" and "Community content" don't exist in the CUBRID Manual…
    - I "played" with the CUBRID Manual, but I wasn't able to view any hierarchy in the left TOC, except for the basic "link-to-parent"…
    - One of the best assets in MSDN is the links from within content, which don't exist in the CUBRID Manual
    - Another design approach - collapsible sections - again, they don't exist…
    - My favorite functionality on MSDN - Search - has no equivalent in the CUBRID Manual
    -  I also agree with missing siblings display mentioned by Esen - it would be great to have it
    and so on…

    Probably the manual could use some re-engineering to implement such improvements…?

    /Daniel

     
  • Esen Sagynov
    Esen Sagynov
    2011-04-06

    1) Since recent times the ordinary pages on cubrid.org can have the "related contents" (e.g. http://www.cubrid.org/cubrid_pdo_driver), however, as I understood from what Catalin has said to me, that module cannot be applied to XE Docs, yet. Hope we can fix this soon. That "related content" module works based on the tags each page has. Briefly, if we want to add this module to the manual, we need to tag each manual page beforehand. For this we can do the following:

       - CUBRID has certain reserved keywords. We can write a short script to traverse all the page titles and see if it they contain any of those keywords. If so, add that keyword to the tag list. This should be the fastest way to accurately add the tags, though it does not guarantee all the pages will be tagged. Perhaps we can find other ways too to cover the rest content.

    2) I thought about the "Community Content". But, first, as we do not have that community, this kind of feature is of less priority. Except MSDN, PHP.net has the same community content under each documentation page. However, the current manual system has the "Commenting System", which allows anyone to post rich-text content below each manual page. Though the current commenting system is quite inconvenient, we will improve its logic.

    3) In-page links is something the CUBRID Manual lacks. Admitted. But once higher priority tasks are completed, I think we can use the same logic from 1) and auto-link to the target pages for each keyword. I also thought about this feature, this is why I started adding internal keyword links in the tutorials (e.g. http://www.cubrid.org/concat_different_row_columns).

    4) Search, mmm…. Admitted. The current search algorithm on cubrid.org should be changed. At this moment, for instance, CUBRID 2.1 pages show up before CUBRID 3.1 pages. Possible we should set to order the same relevancy pages by the latest post/update date. I have already proposed this. It's high priority task now.

    Please keep sharing your opinions, and let's make CUBRID Manual outstand. I believe we can!

     
  • Esen Sagynov
    Esen Sagynov
    2011-04-06

    5) Catalin, currently in the XE Docs search results page, there is no search box. Have to navigate back to refine my search.

    6) Some pages in 2.1 manual have slightly different browser titles (not the content title), e.g.

    3.1-3.0 manual has "ROWNUM, INST_NUM() Function",

    but 2.1 has "ROWNUM/INST_NUM() Function".

    This is why 2.1 link is not displayed among the available versions for this page.

    Regarding this, I haven't tried to modify the title of 2.1. I was not sure if it wouldn't break anything. So, Catalin, answer please, if it is ok to change the title on the go if we find inconsistencies, and if it will automatically be listed among the available version if the titles become the same.

    7) Editing of the manual page doesn't work. When I click on the Edit button, it loads the page's title, but the content belongs to the top root page "Introduction to Manual". Please fix this.

     
  • Overall I think the new manual is much better than the old version (web manual). However we cannot compare with MSDN, indeed, but we should keep improve things and this kind of feedback is very useful. Please see below my comments:

    - regarding the display of the siblings nodes we will implement it
    - regarding 1) and 3) (somehow related) the way I see it:
          a) first we should define all the keywords and functions names - that shouldn't take more than few hours(4-6 hours top)
          b) after that run a script that will parse all the documents and check for references(in order to create in-page links), related pages and actually creates them
          c) all the resulted links and relations between pages should be validated at the end by a person
    - regarding 4) it is not the search algorithm to be changed but only the display mode. We will modify such that 3.1 pages should be the first ones.
    - regarding 5) I agree that we should implement it
    - regarding 6) there is no problem to change the documents title on the go but that will not solve the problem. what should we do is to correct in the original imported archive.
    - regarding 7) I cannot reproduce this on the latest version of cubrid.org. Can you give me some more details? (this was a problem in the past indeed but it was fixed in the last version)

     
  • Esen Sagynov
    Esen Sagynov
    2011-04-20

    Catalin, please report here which items have been fixed/implemented asap.

    8) I see the CUBRID Manual search has been modified. The only thing, I want the search results look like cubrid.org original search results which are similar to what most Search Engines have. And the pagination should be at the bottom similar to cubrid.org.

    9) The Manual version buttons are too cumbersome. Please replace them with the style similar to normal version box available on each manual page. And replace buttons with checkboxes. In addition, they do not need to switch back and forth when they are clicked. For example, when clicked on manual 8.2.1, this button shifts to the left.

    10) For more space on the browser for content, please, if it is possible more the "Edit" and "Delete" buttons on the same line with those red buttons. Anyway, all four of them are displayed only for administrators.

     
  • Esen Sagynov
    Esen Sagynov
    2011-04-20

    The pagination placement fixed. Removed right floating from the "<ul class="searchResult">" element. Do not if you intentionally placed it there.

     
  • Esen Sagynov
    Esen Sagynov
    2011-04-20

    Catalin,

    6) Concerning editing the manual pages. I know you often update the XE Docs module and have to import the manuals all over again. Do I correctly understand your process? Here is what I want, Catalin.

    a) I understand that you import all over again because you need to rebuild the version links, right? If this is the reason, then it is not the most efficient way. What you can do is create a separate table to keep track of page relations. This will be very useful because now on we need to have different language links not just version links. So a separate table is required. Moreover, the page titles in other language will be on that language, so will not match with the original title. This is another reason we need to change this behavior.

    b) Now we need to import the Korean manual, too. For this we need to use different URL convention like http://www.cubrid.org/ko/ which is followed by the rest URI ( manual31/…). Based on /ko or /zh or /jp it should display the page in that language if exists, otherwise, its original English content. Then we need to have corresponding language links for pages if available like "This page is available in:".

    c) We need to be able to add pages to manuals manually. I suppose that directly modifying XE's contents module will be time consuming, and in fact not necessary, this is why here is what I am thinking of. First, create a new page normally as we do on XE admin panel, publish it. Then from the XE Docs admin panel (it should have a view for this) select a particular published page on cubrid.org, indicate its version and language, then add it to the manual. It must not create a copy of this page, just add a link. Later when we try to open that page in Manuals view, it should just extract from the database that content.

    d) From the list of available pages, we need to be able to manually indicate which pages are related (different version or language of the current page). We can do this by linking the pages just like as if we add images. When editing the manual page there should be a button (and a list of already linked pages) which allows us to search from the list of published pages on cubrid.org, select the related page and indicate if it is a different language or a different version of the current page. This would be really great.

    If you have comments, please let me know. This solution would solve all related issues.

     
  • Dear Esen,

    In the latest version that is currently uploaded on cubrid.org the following the items were addressed:
    - sibling nodes
    - item 4)
    - item 5)
    - item 7)

    Basically the old xe docs search was replaced with lucene search and now the results are much more relevant and depend also on the selected module (search only for a certain version of the manual) and default 3.1 manual should come first.
    Also the old xe docs search was case sensitive in case of using CUBRID as database (which is not a problem any more)

    I agree with your comments on items 8, 9, 10 - we will fix/change them.

     
  • Esen Sagynov
    Esen Sagynov
    2011-04-21

    5) Still no search box in the nothing found page.

    11) Currently XE Docs does not handle the requests for pages which do not exist. For instance, assume I am searching for a page 831, so visit http://www.cubrid.org/manual31/831. You should see the broken page. There should be some 404 handling script.

     
  • Regarding 5) we should definitely add the search box in the search results page displayed when there are no results found.

    Regarding no 11)  I already made the redirection for old web manual links to point to the new xe docs instances. However we will also make a mechanism to display something like 404 (or so) when an invalid page from xe docs modules is requested.

     
  • Dear Esen,

    Regarding no 6) let me first try to make things a little bit more clear:
    - updating xe docs module code and re-importing the 3 manuals are not necessary related (only in rare cases when the code changes request this)
    - importing a manual takes about 40 seconds. for 3 manuals it will take about 1-2 minutes
    - when I need to update the source code of xe docs module on cubrid.org I have two options:
       a) make a merge between the old source code and the new source code - which sometimes take 10 minutes and it is      error prone. Also I must first assure that there are no incompatibilities with the old code.
       b) remove first the imported manuals, directly replace the source code and then re-import the 3 manuals and compile them
    - in most of the cases the second option is much easier (takes less time) and it is preferred since I import the manuals under the same module names and the links will be the same for the search engines

    Please see below the answers to your direct questions (basically the scenario is not exactly the one you described):
    a) We keeep version info in xe_document_extra_vars. import process is different from compile versions. compile version is required after we import documents because we need to reestablish relations.
    Compile versions just looks to find document equality in a manual set. This is based on document aliases and document_srl values and version information is afected by importing new manuals.
    Import manuals is a 3 step process that puts togeter all pieces of information from a manual archive , document content, tree structure, images, and aliases.

    b) To achieve this requirement we need first to import korean manual (we need a sample zip file to make sure our import process is OK - I already asked Laura to send us such a zip archive) , Then we need a function that determines document equivalence between different languages and using this we can have enough info to build "This page is available in:".

    d) Manually linking pages is time consuming and error prone I am not sure if this will work .

    Fixing item no 6) is already in progress so lets wait until we finish these modifications and after that we will resume this discussion (if case).

     
  • We have updated the XE Docs module on cubrid.org with the following items fixed: 5)  8)  9)  10) 11)

     
  • Esen Sagynov
    Esen Sagynov
    2011-05-02

    8) Just want you to remind me if XE Docs use nLucene to perform the search. The reason I am asking is the "Summary" block for each search result is a garbage. I will also make some changes to the style. If I do, I will let you know by skype today.

    9) I will also look at it. Want it to look better.

    11) How do you handle the 404? Do you just display the default home page?

     
  • Esen Sagynov
    Esen Sagynov
    2011-05-02

    8) Changed the version buttons look and feel. They are still buttons.

    9) Changed the style to look like cubrid.org.

    12) The Edit/Delete buttons should not appear on search results page. Can you control this?

     
  • Dear Esen,

    Please see my answers below:
    8) Yes, we use nLucene module to perform the search in xe docs module. But it doesn't matter what search method we use as long as the "getSummary" method is a method of the document.item class. It's the same method that is called in the general search of cubrid.org. The problem is with the documents from manuals as we import the content from some html files which are stripped of unnecessary code and sometimes extra new lines remain in the content of the documents. The garbage you mentioned about are actually some new lines characters which are not interpreted by the browser. However we will try clean up those extra new lines when importing the content next time.

    11) A message is displayed like here.

    12) We will try to include this in the next version but I don't this affects in any way the users.

    Also I want to ask you not to make any more changes directly on the server but on the SVN (I'll give you the details on chat) because next time when I update the version of xe docs the changes you made will be lost. Of course, I could make a difference and a merge each time I made an update, but this means waisting time. More than that, committing on the SVN gives us the possibility to have a history log and keep track of the changes. This time we will integrate the changes you made on SVN but starting from now let's use the SVN please. Thank you.

     
  • Esen Sagynov
    Esen Sagynov
    2011-05-12

    Dear Catalin,

    Please import the new CUBRID 8.4.0 Manual today from ftp://ftp.cubrid.org/CUBRID_Docs/Manuals/CUBRID2008R4.0_beta_WebHelp_en.gz.

     
  • Dear Esen,

    We have imported the last version of manual (4.0) into cubrid.org.
    I have one thing to ask you: can we preserve the structure of the zip archives? The problem with the latest version (4.0) zip archive is that it does not contain all the files and folders in the root path of the archive but contains another wrapper folder. Maybe this is not very important for the users but it is important for the xe docs module in order to work properly.
    For the import I've made I had to download the zip, unzip it, make another zip with all the contents in the root path of the archive. Can we please correct this? Thank you.
    Btw, the download speed is pretty slow from that ftp server (from our side). Maybe we can move that ftp server on an amazon S3 and have it replicated on 2-3 locations (mirrored).

     
  • Laura Oh
    Laura Oh
    2011-05-16

    Dear Catalin,
    From the next release, cubrid manual zip file will be exactly what should be for XE doc import.

    About the FTP server, actually ftp server in Korea is linked to an application to show download counts board(dash board)  from FTP server. If the speed matters for global users, we can have additional FTP server on amazon S3 with having the same logic to  accumulate the number of downlaods, otherwise just move the FTP server to S3.
    about this FTP server location, let's pur off for a while and think after dev platform was implemented successfully on cubrid.org. Until then, please stand a low speed.

     
  • Esen Sagynov
    Esen Sagynov
    2011-05-18

    Catalin,

    13) Please remove the old CUBRID logo from the footer of the XE Docs. Instead add the sf.net logo to increase sf.net logo impressions which affects the SF.net ranking.

     
  • Daniel Ionescu
    Daniel Ionescu
    2011-05-18

    Done.

     
  • Esen Sagynov
    Esen Sagynov
    2011-05-19

    Please remove the old logo from CUBRID Forum, too. Thanks.

     
  • Done.

     
  • registry cleaner - registry cleaners - best registry cleaner - clean your pc now , registry checker computer registry cleaner http://www.registrycleaner.us.com/

     
  • Heya i am for the first time here. I came across this board and I find It truly useful & it helped me out much. I hope to give something back and help others like you helped me. Cheap Oakley Sunglasses http://www.tumblebustots.com/