What is your opinion about documentation, in which section of 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 for example helloworld extension 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 you find this solution useful.

[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!