How to document - Githubissues

I see many issues here writing about what to document, but not how. Now, while I do believe you guys are way more experienced than me writing documentation, I just want to give my two cents.

The 5W1H method, or at least at minimum what, why and how, should be used to explain the various Hugo approaches and features.

What is it used for?
Why would I want to use it?
How do I use it? (And also important, how does it work?)
When should I use it?

Let's take an example, shuffle

What

shuffle is a Hugo function that takes a collection (also known as an array, or list) as an argument. It is used to randomize the order of the indeces (elements) in a collection.

Why (This can also include "When", talk about some use cases)

shuffle can be used as part of a random text or number generator. This can solve a problem with two Site.Menu.<menu> pages having the same name.

archetypes/dir1.md

---
title: "Same name"
menu:
  main:
    identity: {{ seq 0 9 | shuffle | delimit "" }} <-- Not really sure if that works
---

/content/dir1/a.md

---
title: "Same name"
menu:
  main:
    identity: 1984273650
---

/content/dir1/b.md

---
title: "Same name" <-- Same title as a.md
menu:
  main: <-- Placed in the same menu as a.md
    identity: 7368012549 <-- However, different identity avoids errors
---

Since Hugo internally automatically sets the identity of the page to the title, two pages with the same identity that is contained within the same menu would clash. By setting the identity to something random, we can prevent this error, and multiple pages can have the same name, even if it is placed within the same menu.

How

To use shuffle, you can either use enclosement with parenthesis: {{ shuffle ( slice "a" "b" "c" ) }} Or by piping: {{ slice "a" "b" "c" | shuffle }} Or use it on a variable: {{ shuffle $array }}

My point of this is that the documentation should not just contain the what and a little bit of how, but also explain why it even exists. What problems does it solve?

rdwatters / hugo-docs-concept

How to document #162

What

Why (This can also include "When", talk about some use cases)

How