Missing User's Guides

[christiankral]

I suppose that each Modelica package shall have a User's Guide

• to give a short introduction into the package,
• to host contact information,
• to host the revision history,
• and summarize all literature references.

Such a User's Guide is currently missing in the following packages:

• Blocks
• Electrical.Analog
• Thermal.HeatTransfer
• Math
• ComplexMath
• Icons already provides the information does not host it in a subpackage User's Guide contains only icons but neither a real User's Guide nor any information underneath. Icons is organized fully flat.
  

I guess we shall add User's Guides to these subpackags.

[AHaumer]

I support this idea, But I don't understand:
"Icons already provides the information does not host it in a subpackage User's Guide"
I suppose those parts should be included in a UsersGuide?

One more question:
Should the parts of a UsersGuide be stord as one file or in a diretcory strudcture as single files?
Personally, I prefer the second one.
I strongly dislike the style that UsersGuide and/or Examples are included in package.mo (like in Blocks)!

[christiankral]

I support this idea, But I don't understand:
"Icons already provides the information does not host it in a subpackage User's Guide"
I suppose those parts should be included in a UsersGuide?

My point is: every sub-library has a UsersGuide which contains at least Contact and ReleaseNotes. The UsersGuide explains what the sub-library is good for, Contact contains the library officers and their contact information, Release Notes contain...

We do not have such a structure in the Icons sub-library. The point of discussion is: Shall we also include a real UsersGuide -- not only the icons -- in the Icons sub-library. After looking at this case again I came to the conclusions that "no" is probably the better answer, as the library is better to understand if it is fully flat organized (as Constants and SIunits). The relevant information is hosted in the Documentation layer of Icons, so that shall be OK.

[christiankral]

I support this idea, But I don't understand:
"Icons already provides the information does not host it in a subpackage User's Guide"
I suppose those parts should be included in a UsersGuide?

One more question:
Should the parts of a UsersGuide be stord as one file or in a diretcory strudcture as single files?
Personally, I prefer the second one.
I strongly dislike the style that UsersGuide and/or Examples are included in package.mo (like in Blocks)!

See #2975 (comment)

[beutlich]

I'd prefer to have UsersGuide.mo as single file. For examples it might be preferrable to have each model as extra file.

[christiankral]

User Guides are still missing for:

• Modelica.Blocks
• Modelica.Math
• Modelica.ComplexMath

[arunkumar-narasimhan]

As pointed out by @HansOlsson in the comment on issue #4247, it would be worth to discuss here if adding release notes to sub-libraries is necessary.