What is your opinion about documentation, in which section of the Readme should credits be put?

[GiovanniSalmeri]

Hello everyone.

Currently in the Readme's of extensions credits are put in the "Installation" section (see for example Bundle, Emoji, Gallery ecc.).

But this might suggest that the library mentioned needs to be installed separately for the extension to work (I saw someone reasoning like this). But credits are only informative, they imply no instruction to follow. If a new section "Credits" is overkill, wouldn't be better to put credits in the "Developer" section? Here the meaning would be: the developer made this extension, relying on the work of others, and no misunderstanding would be possibile.

Any opinion? Thank you very much!

[annaesvensson]

Hello Giovanni. I have to agree that this double-use of the installation section can be confusing, especially for new users who just want to press a button and get on with their normal life. After looking trough some books, I saw that many of my Swedish books have a page with the heading "Tack" at the end, meaning thanks or acknowledgements in English. I suggest to put credits in an optional section "Acknowledgements" before "Installation".

[schulle4u]

Now we have an acknowledgements section, but honestly Im not fully satisfied with the new documentation structure. Putting acknowledgements between the "how to..." and installation section somehow breaks up my reading experience.

I would suggest to make the acknowledgements the last documentation section. Furthermore we should think about moving the developer/designer/translator section. All active developers now maintain their own repositories, and imho it is no longer necessary to keep a separate developer line. Instead we could write down this information in the description line under the top heading, making it a little more identical to the distribution repository. Here is an example documentation file for the stockholm theme:

<p align="right"><a href="README-de.md">Deutsch</a> &nbsp; <a href="README.md">English</a> &nbsp; <a href="README-sv.md">Svenska</a></p>

# Stockholm 0.8.14

Stockholm is a clean theme. Designed by Anna Svensson. [Get help](https://datenstrom.se/yellow/help/).

<p align="center"><img src="stockholm-screenshot.png?raw=true" alt="Screenshot"></p>

## How to customise a theme

All theme files are stored in your `system/themes` folder. All layout files are stored in your `system/layouts` folder. You can edit these files. Your changes will not be overwritten when the website is updated.

The default theme is defined in file `system/extensions/yellow-system.ini`. A different theme can be defined in the [page settings](https://github.com/annaesvensson/yellow-core#settings-page) at the top of each page, for example `Theme: stockholm`. [Learn more about themes](https://datenstrom.se/yellow/help/how-to-customise-a-theme).

## Installation

[Download extension](https://github.com/annaesvensson/yellow-stockholm/archive/main.zip) and copy ZIP file into your `system/extensions` folder. [Learn more about extensions](https://github.com/annaesvensson/yellow-update).

## Acknowledgements

This extension includes [OpenSans](https://fonts.google.com/specimen/Open+Sans) by Steve Matteson. Thank you for the beautiful font.

What do you think? Sorry for partly extending the discussion. 🙂

[annaesvensson]

Here's another alternative. As I recall the installation section was moved to the end because we assumed that the reader would need this section once and other sections all the time. I have to agree with Steffen that this breaks the expectation of many readers, although other sections are read more frequently, it feels like a more natural flow of information to start a software documentation with the installation section. I suggest to explain installation in "How to install XYZ" at the beginning, to put credits in "Acknowledgements" and the responsible developer/designer/author has the honour of the last word.

[GiovanniSalmeri]

Thank you very much for the feedback! As long as misunderstandings are avoided, I have no strong opinions about the order of the sections: after all, typical readme of Yellow are really short 😊. So I cannot decide between @schulle4u 's and @annaesvensson's proposals... I will gladly follow the solution that will be decided!

[annaesvensson]

There's now a new documentation standard, which was named "marzipan edition". See example feature and the above mentioned extensions. There was no consensus on what would be the perfect order for headings, so we probably have to take a solution that everyone is a bit dissatisfied with, hopefully that's good enough. Readme files should use the following order for headings, all are optional:

• How to...
• Examples
• Settings
• Acknowledgements
• Developer / Designer / Translator

[markseuffert]

What do you think, Giovanni? Did you have time to look at the new documentation?

[GiovanniSalmeri]

Sorry to be little present lately... The new pattern of documentation seems perfect to me: very clear and logical!

[annaesvensson]

There's now a new documentation standard called "Matterhorn remix". The following things have been changed. First, file names should use lowercase letters, e.g. readme.md,screenshot.png, extension.ini, it's actually kebab-case which you can see in file names like how-to-make-a-small-website.md. Second, the HTML language switcher has been removed from all readme files, as it would not have worked on different Git hosting platforms. Third, the responsible developer/designer/translator is no longer mentioned at the end of the readme file, instead you write your own name at the beginning of the readme file. Forth, the heading Acknowledgements is now the last one in the readme file. Probably still not perfect for everyone, but hopefully this is an acceptable solution and maybe even an improvement over what we had before. For more details see style guide.