'Creating a Blog' tutorial examples could be improved

gingerchew commented 4 years ago

Affected page(s)

Please provide a link to the page(s) that have an issue, or even better, the link to the source file in the repository. For long pages, please include approximately where the problem is (heading or line numbers)

Creating a blog tutorial page.

What needs to be improved?

Be as specific as possible; is there a typo, incorrect capitalisation of MODX, or does an entire section need work? What is unclear or incorrect? If an inaccuracy or unclear description was discussed on the forums or slack, include a link to that discussion.

The issues are small, but I feel can help lower the barrier to entry and improve the product that beginners create as their first steps. I'm sorry if this is a long list, I will try and balance specificity and generality:

The HTML is out of date and can be improved. Updating it to HTML5 standards (taking advantage of tags like: main, article, section, aside, time).
- Lead by example on accessibility (I'm the accessibility advocate at work, so this one is big for me)
- Improves SEO
- Also include links to documentation like MDN, I don't think it's ever hurt to give someone easy access to good documentation
Remove classes from HTML elements
- Since the tutorial only focuses on HTML and MODX tags, the addition of classes clutters the examples.
- Also if step one is implemented some of the classes can be removed,
- Instead of <div class="postmeta">..., we have <aside>... which inherently suggests information that is related, but not immediately important.
Fix format of some snippet calls
- From the beginners I've spoken to, a long one line snippet is hard to read (looking at you FormIt :P).
- Making these examples multiline will lower the barrier to entry
Fix spacing in examples
- Many beginning developers copy and paste, or will think that is how it is supposed to be spaced. See example below from this section:
```
[[!+page.nav:notempty=`
<div class="paging">
<ul class="pageList">
[[!+page.nav]]
</ul>
</div>
`]]
```
Increase spacing on larger HTML Examples / Creating the examples in reverse
- Make each section; Post Info, Content, Comments, Tagging, Sections, then show the completed product with comments showing each section.
- I defer to the brain trust for this note though, it's not a beach I'm willing to die on so to speak.

Relevant context

Is the problem only in a specific version or language? Then please include that. I've only read through the 'en' version of this page, but I'd be willing to go through and update the other languages as well. Actually, I'd be down to update any HTML in the documentation at all.

I'd love to hear all of your thoughts, I've been going through little by little on this branch - https://github.com/frankie-tech/Docs/tree/update-creating-blog

I haven't completely gone through this page, the editor in me wants to go through 5 more times. I'd never turn down a second pair of eyes though 😃

I'm excited to hear your feedback

Mark-H commented 4 years ago

Looks like you're doing some great work over in your branch - if you'd send a pull request that would make it easier to review the changes. ;)

All improvements, no matter how small, are more than welcome.

gingerchew commented 4 years ago

Awesome! I'll do some tidying and make a PR later today 😄

modxorg / Docs