1. Case study: Version Controlled Documentation - Solution design

    Artikel: AN0002334Aktualisiert: 02.12.2018
    Die vorgegebene Sprachenversion vom Artikeltext wird angezeigt, weil es kein Text von der ausgewählten Sprache und Version gibt.

    We will reflect requirements stated in the above chapter first in the data model. We will draw an entity-relationship diagram and explain meaning of particular entities and their attributes. We will also design a page in which we will display the data.

    Data model

     

    Entity/attribute Description
    Class Language List of languages into which the user can switch the documentation.
       Code Language code.
       Active Indicates whether the language should be used.
       Order Order of the language in the webpart Language selection.
    Class Article List of articles - contains properties common to all article versions varying in language and version.
       Number Unique article identifier - automatically generated sequence.
       Name Internal article name. It is not displayed to readers but only to article editor when selecting parent or related articles. 
       Comment More detailed description of necessary modifications in the article.
       Check content Indicates need to check the article from perspective of content correctness and accuracy.
       Solver Person that is assigned to work on the article.
       Active Indicates that the article should be displayed.
       Last version Last version for which the article is relevant. It is not displayed for higher versions anymore. 
       Topic Including article in a topic (article is assigned either to a topic or to a parent article).
       Parent article Including article in a parent article (article is assigned either to a topic or to a parent article).
       Also Related articles displayed at the article.
       Dashboard order Order of the article in the main page (only articles with this field filled in are displayed in the main page). 
       Order Order of the article in the tree under the parent article. Articles with a filled in order are displayed first. Article without this field filled in are displayed after them according to the Name of the Article text.
       Tag Tags selected at the article.
       Rating Average rating calculated from the previous evaluation.
    Class Article text List of particular versions of the article (texts vary in language and version).
       Article Article, to which the Text belongs.
       Language Language of the Text.
       From version Version, from which the text should be displayed. For older versions the article will not be displayed.
       Name Name of the article. In order to optimize for search engine (SEO) it is included in the page as a part of html tag Title and tag H1.
       URL URL of the article text.
       Comment More detailed description of necessary modifications in the text.
       Published text Text of the article that should be displayed. This text will be copied from the New text, when the editor decides to publish the New text. Article, that does not have this column filled in, will not be displayed.
       New text New version of the text that is being prepared. It will be copied in to the column Published text after publishing.
       Files Files attached to the article.
       Files in page Files that can be diplayed wherever in the page according to the choice of the editor.
       Last published Date of the last update of the column Published text.
       Name in menu Name of the article displayed in menu. If it is not defined, value from column Name is displayed.
       Meta description Text stated in the meta tag Description. Google puts content of this meta tag as the description under the search results. The text should motivate the user to click on the link in the Google search results. 
       Meta keywords Text stated in the page in the meta tag Keywords.
       Display count Article display count.
       Solver Person that is assigned to work on the article text.
       Grammar check Indicates need to perform grammar check of the Article text.
       Translate Indicates need to translate Article text in other languages.
    Class Topic List of topics displayed in the page with the documentation - the highest level of article categorization. Topics are displayed in the main menu of the documentation.
       Name Name of the topic.
       Active Indicates that the topic should be displayed.
       URL URL of the page with topic.
       Order Order of the topic in the page.
    Class Tag List of tags.
       Name Name of the tag.
       Description Localized description of the tag.
       Active Indicates that the tag should be offered to use.
    Class Version List of versions.
       Name Name of the version.
       Display Indicates that the version should be offered in the search. Version, that is at the moment being prepared, will not be displayed, even if articles relevant for it can be created.
       Order Order of the version in the combobox for version selection.
    Class Article display count Count of displays of certain article in certain day.
       Article Article
       Day Day
       Show count Count of displays of the given article in the given day.
    Class Article evaluation Class containing evaluation by users.
       Article Evaluated article.
       Evaluator Evaluator (ObjectGears user) - this is logged when selected in the webpart Rating and the user is authenticated.
       IP Hash of the IP address, from which the Evaluator accessed the page - this is logged when selected in the webpart Rating. It can be used also for the anonymous/unauthenticated user.
       Rating Rating

    Data display

    We will need three screens for displaying the data. The first screen displays particular article with a text corresponding to the selected version and language. There will be hierarchy of the article displayed in the left part of the page. In the upper part of the page there will be menu consisting of selected topics, textbox for entering the searched text, links to social networks and webpart for language selection.

     

    The second screen will display search results. There will be name, tags, meta description (if filled in), code and date of the last article update displayed for each returned article.

     

    The third page will provide the user with list of available tags with their short decription.

    Product version

    The solution has to reflect need to display corresponding documentation for particular product versions. The article can be relevant just for certain product versions. Furthermore, texts may differ for certain versions. We could let editor to create new version of all the articles for each product version. However, this would not be comfortable, mainly if most of articles would not differ from version to version.

    Therefore, we have defined information about version on two places. At the Article level there is last version, for which the article itself should be displayed. At the Article text level there is version from which the text should be displayed. There will be always displayed article text with the highest existing version reflecting version selected by the user.

    In diesem Artikel
    ×