Actions

T3Docs: Vision21

2020-11-03 T3DocsVision21 brainstorming results

Last updated: 2020-11-03

Copied from Notes: [notes.typo3.org](https://notes.typo3.org/86wTR9RQQE2WZmgnaweo8g?both)

Collecting ideas

:::info
You don't have to ask for permission - just login and start writing.
:::

Envisioning TYPO3 documentation in 2021

  • If you were to help: What would be most thrilling to you?
  • What are you missing most?
  • What should definetely be achieved in 2021?
  • What other - phantastic? - ideas do you have?

Make your points and add your email!

Most thrilling to me

  • I am someone who actually LIKES to write documentation (yes!). But I need more feedback. [(sybille)](mailto:)
  • Supportive, inclusive documentation team - everyone is very welcoming. We should be very proud of this. [(Tom)](mailto:)
  • With strong documentation, we can clearly demonstrate what TYPO3 is capapble of and how it can make peoples lives easier. [(Tom)](mailto:)
    • Yes! Strong documentation is a 'trust and vibrancy' signal for open source projects. It shows potential users that the product is active, that it has a thriving community, and gives an non-code way for people to contribute. [(flicstar)](mailto:)
  • ...

What I'm missing most

  • Content-Wise: Straightforward How-Tos with simple steps, best practices and code examples for the 10 most commonly asked questions and tasks, with links to in-depth explanations in other places [(Moritz)](mailto:) +1 [(sybille)](mailto:)
  • Workflow-Wise: What made me do my first contribution? It was the "edit me on github" button - because it's appealing, it featured a guided worflow I was somewhat familiar with, and a GUI including a basic preview for editing which made the process easy. Still, the editing experience remains inconvenient, especially for writing things from scratch, editing structure beyond one single document and moving things, dealing with more complex formatting and assets and so on. That's why I authored rather small edits and refrained from more complex ones. So, despite me being a developer, having a good editing experience would leverage contributions even further. [(Moritz)](mailto:)
  • Live doc updates on code changes (requires different doc rendering workflow since docs need to live in the TYPO3 source repository) [(mbrodala)](mailto:)
  • Clear best practices and workflow (styleguide, coding guidelines, common understanding of how we document things) [(sybille)](mailto:)
  • A real focus on content - the obsession with the infrascture,sphinx etc seems like a massive distraction for a documentation team. * I think too, usage of a CMS is probably an absurd idea (slight sarcasm) [(david)](mailto:)
  • Chain of command, if we as a team make a decision, I want to report this to the core team/gmbh for sign off.
  • Comprehensive templating documentation aimed specifically at new users. [(Tom)](mailto:)
  • regular collaboration and communication between docs + core team + TYPO3 inc [(sybille)](mailto:)
  • Scroller for versions related to single commands i.e. in a sidebar. Alternative just badges on each command with versions. [(david)](mailto:)
  • The main-documentation is getting a monster. While I appreciate reduction of locations/sections/places/manuals in general, I think "TYPO3 Explained" is too huge and the audience is not clearly addressed but just a mix of users, admins, editors, developers - just everyone. Some things are just a bit hard to find.
    Alternative I could imagine tabs inside the pages where each target-group is addressed.[(david)](mailto:) - +1 [(sybille)](mailto:), +1 If not tabs, at least we need to define and target our audience/readers better [(flicstar)](mailto:)
  • Less duplication. [(jonas)]() This needs a strategy, though, where what should go. Example: * Changelogs are currently overused as full documentation. They should focus on the API (added/changed/removed/breaking). They should link to the documentation for examples. On the other hand the documentation should link to the relevant API changelog(s) in order to prevent duplication.
  • Undocumented features or feature changes [(jonas)]() * I think we should have a Signed-Off-By-Docs-Team or a process where the documentation repo needs to have at least an issue before code should be merged.
  • Compacter lists for parameter documentation. The parameter lists are often very long and confusing. A compacter layout could already help. [(naderio)](mailto:)
  • SEO I think it is very important to optimize how the official documentation is found in search engines ecpecially Google. This includes on page and of page seo and especially the content and structure of content. [(lina)]

What should definitely be achieved in 2021

  • Reduce amount of doc locations, sections, places, manuals in general: references + tutorials, walkthroughs, guides only. [(mbrodala)](mailto:) [(+1 sybille)](mailto:)
    • I second this - there is too much to read, and too much to maintain. I mean that in the best possible way :-) [(flicstar)](mailto:)
  • Update + review all docs and find workflow and people to do this in the future [(sybille)](mailto:)
  • A plan, roadmap, overview of (bigger) open tasks [(sybille)](mailto:) (yes, please - [(susi)](mailto:look@susi.dev))
  • Defined projects with dedicated budgets and responsible people for bigger jobs ((re)write) new manuals, wiki.typo3.org migration...)[(susi)](mailto:look@susi.dev) - +1 [(sybille)](mailto:)
  • find incentives for participating - money and beyond, what would motivate an agency to send their people to sprints, how to make it possible for freelancers to participate in bigger projects [(sybille)](mailto:)
  • Allocate extra free money because of Corona travelling restrictions for docs projects [(sybille)](mailto:)
  • Define a decision workflow - who makes big decisions? - example Wiki: how to deal with pre-ELTS documentation [(sybille)](mailto:)
  • Agree an overarching structure for our documentation with the intent of making it as easy as possible to find information on generalised topics, managing content, templating, extension development - see [Laravel's fantastic documentation](https://laravel.com/docs/8.x) // [(Tom)](mailto:). * Yes, let's work on the information architecture. We could do card-sorting activites and user testing to verify decisions. [(flicstar)](mailto:)[(+2 marble)](mailto:)
  • We should also include a plan for the 'baked in' TYPO3 Manual (context sensitive help) [(flicstar)](mailto:)
  • Prioritise content - for example the installation guide could be deemed of high priority meaning it should recieve frequent reviews & updates.[(Tom)](mailto:) [(+1 sybille)](mailto:)
  • Proper datetime handling in database (stored as datetime not as timestamp). It's a mess with timezones, summer-/wintertime. Often, when I select a day (eval date), I get 11:00pm the day before... [(tobik)](mailto:)

Others ideas - yes, even phantastic ones!

  • Find a maintainer (=person) for each manual. This may be a role somebody takes for a defined time like three months.[(marble)](mailto:)
  • It would be nice to have an reST linter. A quick search reveals at least [twolfson/restructuredtext-lint](https://github.com/twolfson/restructuredtext-lint) and [WouterJ/docbot](https://github.com/WouterJ/docbot). Usable?
    It would be great to have something integrated in the editor (phpstorm, vim, sublime, emacs, …) For sublime there already is a plugin "wrap plus" which is great for intelligent reformatting of paragraphs. Further there is a plugin for sublime "rest linter" (untested yet.) [(marble)](mailto:)
  • Extension documentation contest: nominate extensions with great documentation, vote and have prizes [(sybille)](mailto:)
  • Extension documentation contest: pick the best extensions diagrams for the official TYPO3 docs rendering diagram examples section - the current example diagrams are very general (alex - which 'alex'?)
  • restructuredText linting /CGL checking and automatic conversion, add checks to GitHub [(sybille)](mailto:)
  • Start docs initiatives (as in the core) to have several people working on one topic [(sybille)](mailto:)
  • Tutorial: "Getting started with extension development" [(sybille)](mailto:)
    (david would like to do that) (note from [flicstar](mailto:): this is a Guide in the upcoming TYPO3 Book - so it might be useful to leverage some of that content somehow)
  • Tutorial: "Starting a TYPO3 website from scratch" [(sybille)](mailto:)
    (david would like to do that) (note from [flicstar](mailto:): this is also a Guide in the upcoming TYPO3 Book - so it might be useful to leverage some of that content somehow)
  • regular surveys to find out what the community wants - what topics cause difficulties, what documentation is missing [(sybille)](mailto:)
  • Start again - from scratch. New structure, move over existing content that is fit for purpose and get rid of everything that isn't of sufficient quality.
  • how do you determine the quality of existing docs? I think you would need at least 3 people, ideally a topic expert, a beginner or teacher and a native language speaker.
  • [(Moritz)](mailto:) personal wish list for the tool: * State of the art WYSIWYG / preview editing experience with formatting helpers or building blocks * Management GUI to change structure beyond a single document, including creation of redirects * Contribution and review workflow with gatekeepers and TODOs * versioning, activity log (also for rewarding people) and diffs * "content dimensions" (fx. TYPO3 version) for each document or structure * Easy access, fx. SSO with GitHub, Google or TYPO3 LDAP.
  • If there is no open source tool (CMS, wiki, etc.) which fits our needs, we could even consider using a paid and/or SAAS product. Many have been proven to be stable and offer free plans for open source projects like TYPO3. This would free resources (people and money) by leaving development, maintenance and infrastructure work to third parties and would allow us to concentrate on content. [(Moritz)](mailto:)
  • A form to report incorrect or incomplete documentation. [(naderio)](mailto:) I like that idea very much, it could be a low-hanging fruit! [(Moritz)](mailto:)
  • Different paths for documentation and tutorials, like for beginners, ordinary users, experts, or for editors, integrators, developers. [(Riccardo)](mailto:)
  • I don't use proprietary software, so Slack is off limits to me. Is it bridged to IRC or XMPP? [(comradekingu)](mailto:) ⇐ You can just use your browser. [^about-slack]

People

Lines sorted Z - A (why not ;-)

See also

Footnotes

[^about-slack]: Slack offers special features and comes in very handy. AFAIK it's not connected to IRC or XMPP. You don't have to install proprietary software - just navigate to https://typo3.slack.com in your browser. [(marble)](mailto:)

Updated by Martin Bless about 1 year ago · 3 revisions