Documentation/Application Guide/Examples and Wiki

[lvanfretti]

@MaximeBaudette I think we should enable the wiki in the same way you did for RaPId.

There we can add the best practices, validation procedure, application guide, training materials, documentation of test systems, papers and thesis from KTH, scripts (e.g. linearization with OM)...

Can you start with this?

We should use this issue also to discuss how the structure of the Wiki needs to be, and what else we will include.

Wiki is already enabled but restricted to collaborators of the repo. Are we ok with that?

[MaximeBaudette]

@itesla Yes!

[lvanfretti]

@MaximeBaudette @itesla NO, the point of using the wiki is to be able to add all of the possible information for users in different forms.

In fact, already @dietmarw is asking about documentation...

[dietmarw]

My 2 cents, it is normally better to keep the documentation inside the library. Modelica offers the nice way of documenting everything inside via HTML. So only one place to maintain as it travels literally with the code.

Wiki pages might be a nice addon but I would not rely on that as primary source of documentation.

[lvanfretti]

@dietmarw I agree, we can add the application guide and test networks within the library... but I'm not sure how to keep other stuff there.
There are many things (e.g. papers, pdf's, reference models from other SW, etc) that are part of the "documentation" - my intention is that we set up the Wiki to deal with this.

[dietmarw]

I see. Well without knowing the exact content you can of course start with the wiki and one can still decide what can perhaps be included directly in the library. PDFs are very easy to combine by way of putting the files, e.g., under iPSL/Resources/Documentation and then linking to them from User's Guide classes (Resources/ being the recommended location for all non-Modelica code bits in a library). Also references can be organised in a very nice way. The FCSys library for example found an innovative way of including references by (mis)using classes.

[MaximeBaudette]

@dietmarw
I agree that model documentation should reside in the Modelica code. However, our work so far has mainly been of implementing components using other software as reference. Documentation has, thus, not been the priority and I recommended that we simply redirect the user by mentioning the original name of the component and which software documentation to look at.
This can of course be changed in the future as the library mature.
The Wiki was, in my opinion mostly interesting for providing additional info on how to contribute, extended description of the library, and also include documentation on the model validation work that has been done. So far we have mostly done this work in the form of publications, but we have prepared a template document for people to contribute validation report, but I saw it hasn't been uploaded yet in the repository. I'll have a look at it, and will probably put it in the Wiki, instead of the repository as originally intended.
In short, I would like to see the main Readme strongly reduced in the repository and transfer some of its content to the wiki.
@lvanfretti @itesla The idea of keeping the Wiki restricted to collaborators, is, in my opinion, necessary in a first step until we have fully established an architecture and fully documented how we intend to use it.

[MaximeBaudette]

@dietmarw
Another question. I am aware about the HTML-like documentation of Modelica, but so far I have mainly faced issues in using it with Dymola, having to constantly go in the HTML code and fix it manually. The behaviour is also very unstable with what I've experienced, and some of my colleagues have faced the same issues.
Do you have any Modelica editor to recommend for documentation tasks?

[dietmarw]

@MaximeBaudette As long as you avoid the WYSIWY(wishto)G editor of Dymola you are on the safe side. I personally edit HTML in source (using emacs) which works fine and does not give you any nasty surprises (even the Dymola HTML editor works fine as far as I can tell). There is an actively developed Atom.io plugin for Modelica with HTML preview mode available.