{"action":"created","issue":{"url":"https://api.github.com/repos/tbeu/Modelica/issues/78","repository_url":"https://api.github.com/repos/tbeu/Modelica","labels_url":"https://api.github.com/repos/tbeu/Modelica/issues/78/labels{/name}","comments_url":"https://api.github.com/repos/tbeu/Modelica/issues/78/comments","events_url":"https://api.github.com/repos/tbeu/Modelica/issues/78/events","html_url":"https://github.com/tbeu/Modelica/issues/78","id":196279459,"number":78,"title":"Improve quality of the MSL documentation","user":{"login":"modelica-trac-importer","id":22202507,"avatar_url":"https://avatars.githubusercontent.com/u/22202507?v=3","gravatar_id":"","url":"https://api.github.com/users/modelica-trac-importer","html_url":"https://github.com/modelica-trac-importer","followers_url":"https://api.github.com/users/modelica-trac-importer/followers","following_url":"https://api.github.com/users/modelica-trac-importer/following{/other_user}","gists_url":"https://api.github.com/users/modelica-trac-importer/gists{/gist_id}","starred_url":"https://api.github.com/users/modelica-trac-importer/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/modelica-trac-importer/subscriptions","organizations_url":"https://api.github.com/users/modelica-trac-importer/orgs","repos_url":"https://api.github.com/users/modelica-trac-importer/repos","events_url":"https://api.github.com/users/modelica-trac-importer/events{/privacy}","received_events_url":"https://api.github.com/users/modelica-trac-importer/received_events","type":"User","site_admin":false},"labels":[{"id":502947094,"url":"https://api.github.com/repos/tbeu/Modelica/labels/enhancement","name":"enhancement","color":"84b6eb","default":true}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":19,"created_at":"2016-12-18T14:47:48Z","updated_at":"2016-12-18T14:51:28Z","closed_at":null,"body":"**Reported by christiankral on 9 May 2008 11:19 UTC**\n# Issue\n\nIn the scientific community MATLAB is the benchmark for numeric computing. Many new Modelica users therefore know MATLAB and thus compare Modelica with MATLAB somehow. For them, one criterion is the documentation of the MSL, because \n * they need to understand how the models work, and\n * they have to decide which models they are going to use. \nThe documentation of the MSL is thus an important issue.\n\nFor myself, the MATLAB documentation is a benchmark and the quality of the MATLAB documentation is really great. In MATLAB the user gets a text screen help typing HELP MODEL. A more advanced and better formatted documentation is available by typing DOC MODEL. The latter one is the reference I am talking about. I shortly summarized the advantages of the MATLAB documentation:\n * The documentation is standardized: it looks the same for different scrips and functions\n * The documentation contains different sections\n   * Description: explains how the MODEL works\n   * Examples (optional): if required/useful\n   * Limitations (optional): explains the limitations of the MODEL\n   * Algorithm (optional): explains how the implementation is made\n   * References (optional): literature\n   * See also: shows hyperlinks to related scripts and m-files\n * The layout format of the documentation is the same for every model\n\nSince we are using HTML for the Modelica documentation we should also be able to provide a high quality documentation. The MSL is a professional library, but and the documentation looks different and is of different quality for every other package. If we want to attract further users, I think we have to improve the quality of the documentation of the MSL.\n\n# Current status of libraries\n\n * Some packages do neither have a version number nor a version date, e.g. `Analog`, `Blocks`, `Digital`, etc.\n * The `Modelica.Thermal.HeatTransfer` has a link to a commercial web site: `www.amazon.de`\n * In the documentation variables and parameters are having mixed formats:\n   * <b>bold</b>, e.g. in `Modelica.Thermal.HeatTransfer`\n   * normal, e.g. in `Modelica.Thermal.FluidHeatFlow`, `Modelica.Electrical.Machines`\n   * <i>italic</i>, e.g. in `Modelica.Blocks`, `Modelica.Electrical.Analog`\n   * \"quotes\", e.g. in `Modelica.Math.Matrices`, `Modelica.Mechanics.MultiBody`\n * The documentation is sometimes not correct, e.g. `Modelica.Blocks.Continuous`, where input and output are (still) meant to be vectors instead of scalars\n * The documentation of some models is sometimes not present, e.g. `Modelica.StateGraph.PartialCompositeStep`\n * Some models are empty, e.g., `Modelica.StateGraph.Examples.FirstExample`\n * Different capitalization of the documentation text (starting/Starting with upper/lower case)\n * Hyperlinks to other models most of the times often missing\n * The documentation of each package is differently structured\n\n= Proposal = \n\nThis subject should be discussed at the Modelica Design Meeting. A proposal for the unification of the documentation comprises the following:\n\n * Unification of the structure of the documentation\n * Unification of the format of the documentation (variables, parameters, models, references)\n * Unification of versioning: what? how?\n * Improve quality of content and add more illustrations (results) -- in particular to the test models in the `Examples` subpackages\n\n## Structure of Modelica documentation\n\nThe following subsections should be added to the documentation:\n * Description: explains how the MODEL works\n * Examples (optional): if required/useful\n * Limitations (optional): explains the limitations of the MODEL\n * Algorithm (optional): explains how the implementation is made\n * References (optional): literature\n * Notes (optional): if required/useful\n * Acknowledgements (optional): if required\n * See also: shows hyperlinks to related models\n * Revision history: if required/intended for a package/model\n\n## Format of the Modelica documentation\n\n * Unification of the format for parameters and variables, e.g. `<code>variable</code>`, since in this case equations formatted by `<pre>...</pre>` have the same format as variables and parameters -- which should be achieved\n * Unification of citation formats for articles, books, manuals, etc.\n * Refer to other models, functions, etc., always through a hyperlink\n * Define format of subsections e.g. `<h4>Description</h4>` \n * Define format of how version history is displayed (e.g. table with version, version_date, author, comment) including order  (ascending or descending version numbers).\n * Define mandatory guidelines for typeset of complex equations with `<pre>...</pre>`\n * Define how to emphasize a phrase or word (bold or italic)\n * Define on how to refer to a Modelica specific term, e.g. Integer, bus, expandable bus, e.g. omit format (emphasizing)\n * Unify capitalization of the documentation text (starting/Starting with upper/lower case) for\n   * subsections\n   * after a :\n   * in a list\n   * in the version history\n   * etc.\n\n## Additonal issues to be discussed\n\n * Shall a version history be provided for each model? A version history for each independently developed package, I think, should be mandatory.\n * Does it make sense to unify the version number handling, e.g. X.Y.Z \n   * X: main version; a change in X means a big improvement\n   * Y: regular planned releases\n   * Z: bug fixing\n * Should a User's Guide/Tutorial be added to each independently developed package ?\n\nMigrated-From: https://trac.modelica.org/Modelica/ticket/78"},"comment":{"url":"https://api.github.com/repos/tbeu/Modelica/issues/comments/267825415","html_url":"https://github.com/tbeu/Modelica/issues/78#issuecomment-267825415","issue_url":"https://api.github.com/repos/tbeu/Modelica/issues/78","id":267825415,"user":{"login":"modelica-trac-importer","id":22202507,"avatar_url":"https://avatars.githubusercontent.com/u/22202507?v=3","gravatar_id":"","url":"https://api.github.com/users/modelica-trac-importer","html_url":"https://github.com/modelica-trac-importer","followers_url":"https://api.github.com/users/modelica-trac-importer/followers","following_url":"https://api.github.com/users/modelica-trac-importer/following{/other_user}","gists_url":"https://api.github.com/users/modelica-trac-importer/gists{/gist_id}","starred_url":"https://api.github.com/users/modelica-trac-importer/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/modelica-trac-importer/subscriptions","organizations_url":"https://api.github.com/users/modelica-trac-importer/orgs","repos_url":"https://api.github.com/users/modelica-trac-importer/repos","events_url":"https://api.github.com/users/modelica-trac-importer/events{/privacy}","received_events_url":"https://api.github.com/users/modelica-trac-importer/received_events","type":"User","site_admin":false},"created_at":"2016-12-18T14:51:28Z","updated_at":"2016-12-18T14:51:28Z","body":"**Comment by christiankral on 1 Sep 2010 06:53 UTC**\nSo far we only achieved writing down a specification for the MSL documentation. Most of the documentation is not yet improved, e.g., not every package is having a User's Guide. Paid work for improving the documentation has not been initiated yet. Thus the ticket is not yet fixed."}}
{"actor":{"display_login":"modelica-trac-importer"}}