BD-3069 Diataxis templates

[rachel-feinberg]

Pull Request/Issue Resolution

Description of Change:

Adding Diataxis templates to the contributing section

Closes #BD-3069

Is this change associated with a Braze feature/product release?

• Yes (Insert Feature Release Date Here)
• No

[internetisaiah]

@rachel-feinberg Overall this is great stuff! Thanks for putting it together!! Sorry it took me so long. As I go through this, here is my main takeaway that I'm thinking: Slightly tweak the structure of each section so it flows a little more like the following. The main goals being:

1. Offer a template for each page type for easy copy + paste.
2. Use real examples without placeholders throughout the page, so people can see a real world example.

Thoughts?

## How-tos

How-to guides are action-based, chronological steps that show users how to complete a specific task.

{% details Show template %}
{% raw %}
```
ADD TEMPLATE HERE WITH PLACEHOLDERS
```
{% endraw %}
{% enddetails %}

### Guidelines

- List item
- List item
- List item

## Headers

For how-tos with long or complicated steps, use nested headers to group related steps as shown in the following Markdown sample. For short steps, see [Ordered lists](#ordered-lists) instead.

```
REAL EXAMPLE WITH NO PLACEHOLDERS
```

### Ordered lists

For how-tos with short and straightforward steps, use an ordered list in Markdown format.

```
REAL EXAMPLE WITH NO PLACEHOLDERS
```

Then maybe (if this makes sense), we pull in the partner template and release notes template from the templates.md page and then delete that page entirely?

[rachel-feinberg]

@rachel-feinberg Overall this is great stuff! Thanks for putting it together!! Sorry it took me so long. As I go through this, here is my main takeaway that I'm thinking: Slightly tweak the structure of each section so it flows a little more like the following. The main goals being:

1. Offer a template for each page type for easy copy + paste.
2. Use real examples without placeholders throughout the page, so people can see a real world example.

Thoughts?

Then maybe (if this makes sense), we pull in the partner template and release notes template from the templates.md page and then delete that page entirely?

I applied the majority of your edits! I think the only one I didn't apply is using real examples...because I copied & pasted them from existing articles. If they have placeholders, those were included in existing articles. I think back when I created this, I struggled with finding good examples that already followed the guidelines, so if you have ideas for replacing any of them, I'm open to them!

The PR is updated with the changes, so you can check out the latest deployment (when it's up; I heard there might be issues on Vercel's end).

[internetisaiah]

@rachel-feinberg , heads up, i have some changes that i'm almost done with that i'm going to push up in the next few hours. i guess while re-reading this, i'm realizing that some of the problems i couldn't solve were: the doc wasn't very "diataxis" itself 😂 ! oversight on my part! so i'm rewriting the first section to be more reference-style, then we can use that to reformat the other sections. i'll tag you when i'll be ready for that next part 👍🏽

[internetisaiah]

ok @rachel-feinberg , apologies for the delay here. i just rewrote the How-to section to try to simplify the content + make it more reference-like in its tone/approach.

after you read it over, let me know if you have any thoughts/suggestions.

if we are on the same page for that section, can you apply a similar format to the rest of the sections on this page so they match the flow/tone/style of the new How-to section?

THANKS 🙌🏽

[internetisaiah]

@cla-bot check

[cla-bot]

The cla-bot has been summoned, and re-checked this pull request!

[internetisaiah]

LGTM! 🎉 Great work here Rachel, and the new edits were on point. FYI I also added descriptions for each of the categories listed under the Release Notes. Since I'm not as familiar with these, could you double check my descriptions and make any tweaks as needed 👍🏽

Other than that, merge whenever you're ready ✅

[internetisaiah]

Note: I darkened the example screenshots since they felt way to similar to the content on the page and were making my eyes confused haha.