Case study: Version Controlled Documentation - Solution design

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.