Skip to content

Instantly share code, notes, and snippets.

@sypets

sypets/Proposal_TYPO3_blogs.rst

Last active September 14, 2020 10:47
Show Gist options
  • Save sypets/8c9d892818c41d61a9a518857890734a to your computer and use it in GitHub Desktop.
Save sypets/8c9d892818c41d61a9a518857890734a to your computer and use it in GitHub Desktop.
Download ZIP
TYPO3 Proposal - Improve documentation - blogs
Raw
Proposal_TYPO3_blogs.rst

Proposal: Improve TYPO3 documentation - blogs

Summary TL;DR

When you blog about TYPO3 and your blog is actually documentation (more or less), see if you can make it easier for new users by:

  1. Add version tags to your blog entries. These can be tags specifying for which major TYPO3 version(s) your text applies and are shown on the top of the page, see for example https://usetypo3.com/ or https://daniel-siepmann.de/
  2. Keep your blog entry updated, add a notice or remove when no longer helpful, outdated or no longer adheres to the best practices
  3. Help to improve documentation on docs.typo3.org too!

Suggestions

These are some tips which might counteract some of the drawbacks (mentioned below under motivation):

Do at least one of these to keep your blog helpful:

  1. Show the date when a blog entry was created, last updated (see https://daniel-siepmann.de/)
  2. Keep the blog entry up to date or show a hint at the top that it is no longer up to date if it is not up to date
  3. Remove outdated content, content that does not adhere to best practices
  • Make it possible to search or filter by TYPO3 version
  • Link to documentation: If something is currently well documented on docs.typo3.org, link to the documentation

Nice to have:

  • Create a voting system to up / downvote pages
  • Create a possibility to leave comments or give feedback

In addition to these suggestions:

One of the reasons that you are writing a blog article in the first place may be that the current documentation on docs.typo3.org might not be helpful when it comes to a specific subject or use case. This may have several reasons: it may be outdated, it may even be missing or it may not be helpful for the most common use cases.

If you can help with that, it is very much appreciated. Writing a blog article might be a first step, but please check if you can take this a step further and improve the documentation on docs.typo3.org.

These are some things you can do to help the documentation on docs.typo3.org:

  • Point out outdated, missing or not helpful documentation on docs.typo3.org and ideally help to improve it: If you find that the documentation on docs.typo3.org is not sufficient, see if you can help to improve this:
    • Create an issue: On the page with a problem, scroll to the bottom and click on "Issues"
    • Fix the page: Use "Edit on GitHub" or work locally with Git, using the Docker image to test your changes locally.

Motivation

The goal of this proposal is to give some recommendations for blog authors which might conteract some of the current problems with documentation in general.

The main goal is to provide helpful and up-to-date documentation for everyone.

We are mostly talking about blog entries, but this includes online TYPO3 documentation of any form which is published outside of docs.typo3.org.

Blogs augment TYPO3 documentation. Often a blog entry is published explaining a new feature and giving a step by step introduction into using this new feature.

This has several drawbacks

  • The blog entries are (as is typical for blogs) usually a once only thing, meaning they will not get updated
  • It is very difficult for new users to determine for which TYPO3 version(s) the blog entry applies or if it is still relevant or even correct and up to date
  • The documentation (as a whole) is very fragmented, with some things documented on docs.typo3.org, some things in the Wiki and some things outside of docs.typo3.org and wiki.typo3.org
  • It is difficult for new users to determine which pages they can "trust", meaning they contain up to date and helpful information. Experienced TYPO3 users often already know where to look. New users do not. They usually hope to find relevant information on docs.typo3.org

The question of why TYPO3 is documented a lot in blogs (instead of on docs.typo3.org) is also an important question and it might be a good idea to adress this, but this is not the scope of this gist.

This gist attempts to improve the current situation as best as possible by making a few suggestions.

A long term improvement of docs.typo3.org and updating of content is of course an important goal but cannot be acchieved overnight.

Sybille Peters - Last updated: Apr 7, 2020

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment