Please improve documentation in README.md file

[germanvaleroelizondo]

Hi,

I translated the English language strings for this plugin into Mexican Spanish in AMOS.

I intended to create a Moodle Docs page in Spanish about this plugin, but I could not get it to work in my local 3.6 server. I am a veterinary pathologist at the largest Mexican University, with no CSS knowledge, like most Moodle teachers.

I think this plugin would greatly improve its usefullness if you could add more detailed documentation, so that a non-programmer reader can actually produce (and use) the five styles illustrated in the screenshot.

Please enclose the text (or a screenshot of it) for the CSS class definitions for Boost.

Please enclose the text for the Styles configuration that will produced the styles shown in the screenshot. I think this text should be used as the actual example in the plugin code.

I think this should not be too difficult nor time consuming for you, but it would greatly help many potential users of this plugin.

Thanks in advance.

[abias]

Hi Germán,

first, let me thank you for translating this plugin into Mexican Spanish. I have read your name many times in the AMOS forum and I am grateful that you help to localize Moodle core and plugins into your language!

Then, let me raise some concerns about creating Moodle docs pages for our plugins. I agree that Moodle docs pages can be translated. But they also have to be maintained when new plugin versions are released. As plugin maintainer, we maintain our documentation in the plugin's README.md file and don't have the resources to keep an additional documentation in the Moodle docs up to date.

Then, regarding your reported issue: I think you are completely right that the existing documentation of the plugin can be improved. When we created the plugin, it was meant as a bridge between a custom theme (or custom CSS in a standard theme) and the Atto editor (which was only able to apply standard paragraph styles back then). We assumed that admins who install the plugin know how the write and install the CSS rules in the theme and know how to create and install the necessary JSON data structure in the plugin's configuration. But you are right, there are also teachers out there who run Moodle installations. I would make sense to serve a low-level documentation for teachers.

So, if I understood you correctly, it's about the documentation section on https://github.com/moodleuulm/moodle-atto_styles#1-configure-css-classes, right? Currently, I am just telling you there to write your CSS and add it to your theme. But there is no example CSS code which you could take and use. And it's about the screenshot on https://moodle.org/plugins/atto_styles, right? This screenshot is a subset of the custom CSS styles which we provide here at Ulm university. I would be more than happy to take our existing custom CSS styles, add them to https://github.com/moodleuulm/moodle-atto_styles#1-configure-css-classes as ready to use CSS code and change the example JSON code on /admin/settings.php?section=atto_styles_settings (which comes from the language pack) to these custom CSS styles.

Could you please confirm if this is what you are looking for?

Thanks, Alex

[germanvaleroelizondo]

Yes Alexander,

If you could do that, it would be great.

I intend to write a Moodle Docs page similar to those for the plugins of the AMC (https://moodle.org/plugins/browse.php?list=contributor&id=1765078 ), which start with this paragraph:

Note: You can find the most up-to-date English and German documentation for this plugin in the AMC website at http://www.academic-moodle-cooperation.org/en/module/offline-quiz/. This page is intended for users who clicked on the 'Moodle Docs for this page' link and for Moodle users of languages other than English and German (IN OTHER LANGUAGES at the bottom of this page).

Would that be OK for you and your University?

[germanvaleroelizondo]

Any progress on this ?

[abias]

Hi @germanvaleroelizondo ,

thank you for pinging me again. This issue was not lost, I only postponed it for our 3.7 release and I forget to tell you this.

So we would be improving the examples given within the plugin to reflect more or less what you see in the screenshot in the plugins repo. I have just created these styles and configurations and have also added some examples for an inline textmarker style.

Here is a sneak peek for the CSS code which you would have to add to your theme (in Boost: In the RAW SCSS setting):

.attostylesbox {
    padding: 10px;
    box-sizing: border-box;
    border-radius: 5px;
    margin-bottom: 10px;
    width: 100%
}
.attostylesbox.attostylesbox-solid {
    color: white;
}
.attostylesbox.attostylesbox-outline {
    background-color: white;
    border-width: 2px;
    border-style: solid;
}
.attostylesbox.attostylesbox-callout {
    background-color: white;
    border: 1px solid #eee;
    border-left-width: 5px;
}
.attostylesbox.attostylesbox-solid-blue {
    background-color: #7d9fd3;
}
.attostylesbox.attostylesbox-solid-green {
    background-color: #98ca3e;
}
.attostylesbox.attostylesbox-solid-yellow {
    background-color: #ffcf35;
}
.attostylesbox.attostylesbox-solid-red {
    background-color: #ef4540;
}
.attostylesbox.attostylesbox-solid-black {
    background-color: #3a3a3a;
}
.attostylesbox.attostylesbox-outline-blue {
    border-color: #7d9fd3;
    color: #7d9fd3;
}
.attostylesbox.attostylesbox-outline-green {
    border-color: #98ca3e;
    color: #98ca3e;
}
.attostylesbox.attostylesbox-outline-yellow {
    border-color: #ffcf35;
    color: #ffcf35;
}
.attostylesbox.attostylesbox-outline-red {
    border-color: #ef4540;
    color: #ef4540;
}
.attostylesbox.attostylesbox-outline-black {
    border-color: #3a3a3a;
    color: #3a3a3a;
}
.attostylesbox.attostylesbox-callout-blue {
    border-left-color: #7d9fd3;
}
.attostylesbox.attostylesbox-callout-green {
    border-left-color: #98ca3e;
}
.attostylesbox.attostylesbox-callout-yellow {
    border-left-color: #ffcf35;
}
.attostylesbox.attostylesbox-callout-red {
    border-left-color: #ef4540;
}
.attostylesbox.attostylesbox-callout-black {
    border-left-color: #3a3a3a;
}
.attostylestextmarker {
    border-radius: 5px;
    padding-left: 5px;
    padding-right: 5px;
}
.attostylestextmarker.attostylestextmarker-green {
    background: #99ffcc;
}
.attostylestextmarker.attostylestextmarker-pink {
    background: #ffccff;
}
.attostylestextmarker.attostylestextmarker-yellow {
    background: #ffffcc;
}

And here is the sneak peek for the atto_styles configuration:

{
    "title": "Red box (solid)",
    "type": "block",
    "classes": "attostylesbox attostylesbox-solid attostylesbox-solid-red",
    "preview": true
},
{
    "title": "Red box (outline)",
    "type": "block",
    "classes": "attostylesbox attostylesbox-outline attostylesbox-outline-red",
    "preview": true
},
{
    "title": "Red box (highlighted)",
    "type": "block",
    "classes": "attostylesbox attostylesbox-callout attostylesbox-callout-red",
    "preview": true
},
{
    "title": "Green box (solid)",
    "type": "block",
    "classes": "attostylesbox attostylesbox-solid attostylesbox-solid-green",
    "preview": true
},
{
    "title": "Green box (outline)",
    "type": "block",
    "classes": "attostylesbox attostylesbox-outline attostylesbox-outline-green",
    "preview": true
},
{
    "title": "Green box (highlighted)",
    "type": "block",
    "classes": "attostylesbox attostylesbox-callout attostylesbox-callout-green",
    "preview": true
},
{
    "title": "Yellow box (solid)",
    "type": "block",
    "classes": "attostylesbox attostylesbox-solid attostylesbox-solid-yellow",
    "preview": true
},
{
    "title": "Yellow box (outline)",
    "type": "block",
    "classes": "attostylesbox attostylesbox-outline attostylesbox-outline-yellow",
    "preview": true
},
{
    "title": "Yellow box (highlighted)",
    "type": "block",
    "classes": "attostylesbox attostylesbox-callout attostylesbox-callout-yellow",
    "preview": true
},
{
    "title": "Blue box (solid)",
    "type": "block",
    "classes": "attostylesbox attostylesbox-solid attostylesbox-solid-blue",
    "preview": true
},
{
    "title": "Blue box (outline)",
    "type": "block",
    "classes": "attostylesbox attostylesbox-outline attostylesbox-outline-blue",
    "preview": true
},
{
    "title": "Blue box (highlighted)",
    "type": "block",
    "classes": "attostylesbox attostylesbox-callout attostylesbox-callout-blue",
    "preview": true
},
{
    "title": "Black box (solid)",
    "type": "block",
    "classes": "attostylesbox attostylesbox-solid attostylesbox-solid-black",
    "preview": true
},
{
    "title": "Black box (outline)",
    "type": "block",
    "classes": "attostylesbox attostylesbox-outline attostylesbox-outline-black",
    "preview": true
},
{
    "title": "Black box (highlighted)",
    "type": "block",
    "classes": "attostylesbox attostylesbox-callout attostylesbox-callout-black",
    "preview": true
},
{
    "title": "Yellow text marker",
    "type": "inline",
    "classes": "attostylestextmarker attostylestextmarker-yellow",
    "preview": true
},
{
    "title": "Green text marker",
    "type": "inline",
    "classes": "attostylestextmarker attostylestextmarker-green",
    "preview": true
},
{
    "title": "Pink text marker",
    "type": "inline",
    "classes": "attostylestextmarker attostylestextmarker-pink",
    "preview": true
}

Is this what you are looking for or have you any change requests?

Regarding the Moodle docs page which you proposed to write, I am still hesitant about it as outlined about. However, if you add a note similar to the AMC plugins' note to the docs page, I expect that it should be ok to build this page if it is helpful for non-english readers.

Cheers, Alex

[germanvaleroelizondo]

Thanks. I will be looking forward to your next version release.

[germanvaleroelizondo]

Any progress on your 3.7 version? Any estimate on having it available in the Moodle plugins database ?

[germanvaleroelizondo]

I just tried your LMS-3906 branch with your suggestions from above and IT WORKS BEAUTIFULLY :)

Can you please add those suggestions to the help file for all users to see when first installing and seting up this plugin?

That would make an extremely user-friendly, easy-to-configure, ready-to-use, usefull plugin.

Great work

[abias]

Hi @germanvaleroelizondo ,

thank you for your patience while waiting for this improvement and the 3.7 version.

Can you please add those suggestions to the help file for all users to see when first installing and seting up this plugin?

Please let me answer this last question of yours. We did not want to add these suggestions to the settings description as we thought it would clutter the settings page too much and because we were afraid that these examples, as soon as they end up in AMOS, would be a burden for translators. In fact, we even reduced the examples on the settings page in the 3.7 version. But we added a link to https://github.com/moodleuulm/moodle-atto_styles/blob/master/README.md#usage--settings where admins can easily find and copy the example.

I hope that this solution will also please you and thank you again for proposing this improvement.

Cheers, Alex