wbamberg/howtos and guides

## howtos and guides
Patrick asked (I think, please lmk if I misrepresented): if we use Divio for our docs, when should stuff be in guides (explanations) and when should it be in how-tos? For instance, I'm writing as guide about offline and backgrond, and will talk about using the background fetch API, and it feels natural to include code samples for things like initiating a bg sync https://pr25305.content.dev.mdn.mozit.cloud/en-US/docs/Web/Progressive_web_apps/Guides/Offline_and_background_operation#registering_a_sync_event. But will this overlap with How-tos, and what kind of content should go in which place? I think these are good questions and I've been thinking the same thing.

I'm not going to rehash Divio here because it's better said elsewhere: https://documentation.divio.com/.

I talked this over with @Florian Scholz and this is my understanding of the conversation.

1. It's fine to have code samples inside guides. It helps break up the text and is easier for a lot of people to read than a textual description of the code.

2. But, a how-to shows a complete end-to-end solution for a specific problem. So the code samples need to cohere and to start with the start of the problem. In a guide the code samples are just illustrative. A guide (in cases like that PWA guide anyway) is intended to show people the kinds of things that are possible, but doesn't have to give you everything you need to know to do a particular one of those things. You probably read a guide when you don't yet know what you want to do, but you always read a how-to when you do know what you want to do, but you don't know how.

3. A guide can and should, IMO link to how-tos that do give you everything.

4. It's inevitable for there to be some duplication between guides and how-to (and reference). Often they are covering the same thing, but from different aspects.

5. I think we're also figuring this out as we go, and I'm happy for us to rework bits of guides if we think they live better in how-tos. From a practical POV (for the PWA project, say) I think we should just not worry about duplication at the moment - for example, list out all the How-tos which we think are needed - and refactor the docs to reduce duplication when it seems needed.

I'm interested in what people think about this!
	Patrick asked (I think, please lmk if I misrepresented): if we use Divio for our docs, when should stuff be in guides (explanations) and when should it be in how-tos? For instance, I'm writing as guide about offline and backgrond, and will talk about using the background fetch API, and it feels natural to include code samples for things like initiating a bg sync https://pr25305.content.dev.mdn.mozit.cloud/en-US/docs/Web/Progressive_web_apps/Guides/Offline_and_background_operation#registering_a_sync_event. But will this overlap with How-tos, and what kind of content should go in which place? I think these are good questions and I've been thinking the same thing.

	I'm not going to rehash Divio here because it's better said elsewhere: https://documentation.divio.com/.

	I talked this over with @Florian Scholz and this is my understanding of the conversation.

	1. It's fine to have code samples inside guides. It helps break up the text and is easier for a lot of people to read than a textual description of the code.

	2. But, a how-to shows a complete end-to-end solution for a specific problem. So the code samples need to cohere and to start with the start of the problem. In a guide the code samples are just illustrative. A guide (in cases like that PWA guide anyway) is intended to show people the kinds of things that are possible, but doesn't have to give you everything you need to know to do a particular one of those things. You probably read a guide when you don't yet know what you want to do, but you always read a how-to when you do know what you want to do, but you don't know how.

	3. A guide can and should, IMO link to how-tos that do give you everything.

	4. It's inevitable for there to be some duplication between guides and how-to (and reference). Often they are covering the same thing, but from different aspects.

	5. I think we're also figuring this out as we go, and I'm happy for us to rework bits of guides if we think they live better in how-tos. From a practical POV (for the PWA project, say) I think we should just not worry about duplication at the moment - for example, list out all the How-tos which we think are needed - and refactor the docs to reduce duplication when it seems needed.

	I'm interested in what people think about this!