"Discussions" as a template type is an overloaded name.

[jaredmorgs]

Gloria Ma 12:41 14 Nov
SELECTED TEXT:

Discussions

I somehow find this word to be confusing here - I think of a discussion like a "forum", as if this template is intended to facilitate a discussion. Whereas based on this description, I think it's really a "background" or "context" article - could those be more intuitive words?

[bwklein]

It does seem like the intention is to provide a starting point or anchor for a point of discussion or dialog.
https://github.com/thegooddocsproject/templates/blob/master/discussion/about-discussion.md#structuring-discussion-articles

[waldyrious]

For the record, the popular four-part documentation system by Divio originally contained four types:

Tutorials, How-to guides, Discussions and Reference

but they later changed to

Tutorials, How-to guides, Explanation and Reference

...presumably due to the same ambiguity. I too feel alternative terms ("overview", "context", "background", "explanation", or even the classic "manual") would be clearer than "discussion", even if the latter can be somehow justified.

[flicstar]

Thinking about this, I am happy with the term "explanation".
In my past experience, we would internally call this a concept topic but then in the docs we'd title it "About blah". I also like "overview" but I think "explanation" is plainer English.

[bwklein]

If the intent of that section is to provide background information and to explain something (background info, etc.) then I agree with Explanation as a choice. It seems to be the point of that article type from the first sentence.

"Discussions, or explanations, explain background information and provide context-specific knowledge on a particular topic."

[adohertyTS]

Per the consensus of this thread (which I agree with), I think we should change all the naming within Templates that currently refers to the doc type "Discussions", to instead refer to "Explanations". +1 on this.

[acpkendo]

+1 that "Explanations" is a better term for this concept than "Discussions."

[aidanatwork]

OK, I made some changes to resolve this issue. If folks have further suggestions to improve the language, let's tackle them in a new issue. Closing this out.