Update Documentation

[csidirop]

Description

The documentation and instructions are incomplete and make it very difficult to get started.
Good documentation allows not only first-time users but also users after an update to a new version to get the system up and running more quickly and easily.

Another more in-depth suggestion would be to consider hosting the documentation here on Github and linking it as an external manual in the TYPO3 extension page.
This would bundle the information on a central page, simplify editing and enable contributions without the full Docker setup.

Problem

1. Need of proper overview

The way the TYPO3 Docs are shown gives not a good overview. Consider adding a TOC or Intro or Overview page in which we could organize the docs. Additionally we should use more tree childen .. toctree::

2. Administrator Manual and System Setup

1. Whats the logical difference? "Administrator Manual" describes the installation and upgrade processes, while the "System Setup" describes how to setup TYPO3 and install Solr.
   -> I think merging them would make the manual clearer.
   -> Alternatively we could make more small docs: eg."Setup: Installation % Upgrade" and "Setup: Tenant" in a subfolder

2. In addition, a setup of the pages (e.g. viewer, search and collections) is missing here.

3. For better testing provide example METS which are working to test:

   • Simple document with FT
   • Newspaper
   • Audioplayer
   • 3D Viewer

   In that way new instances can better test there setup.

4. System Setup: Extension Configuration:

   1. What should the user check?

5. TypoScript Basic Configuration

   1. How to include the Template

6. Slug Configuration

   1. Here is a lot missing! eg.: with all the new querie parameter we need aspects to cover them (if we want to)

7. Solr Configuration

   1. add TYPO3 setup

3. Plugin Reference

• Some plugins have an introducing info text, but most haven't. Missing explanations:
  • Basket
  • List View
  • Metadata
  • Navigation
  • OAI-PMH
  • Page Grid
  • Page View
  • Search
  • Statistics
  • Table Of Contents
  • Toolbox
  • Fulltext Tool
  • Search in Document Tool

4. Features and Testing

• What exactly should be here? Should this be child/sub tree of Developers?
• We should add an overview of all querie parameter (see [Question] Purpose of tx_dlf_navigation query string #974), because most of them are not self-explanatory and its unclear what they are doing or even why they are there.

My project ended with the end of the year, so I wanted to finally add a few points to the documentation before it gets lots. But while writing I realize that there is a lot more work to be done. What do you think?

Estimated Costs and Complexity

I estimate this to be of low cost.
I estimated 1-3 hours for the restructuring. Adding the missing information will take longer. I have estimated 2 working days for this (depending who is writing this).

[michaelkubina]

I agree with you and i was thinking about writing an issue about improving the documentation as well. But now you have been faster...withing the Plugins there is a possibility to add Descriptions for each setting as well, which has not been done. This makes the usage more like a try and error aproach.

I believe this would be worth to be considered for the new development fund 2024. Would you mind to add the label?

[csidirop]

I cant label it, but @sebastian-meyer could. If we should use the fund template, I can also create a new issue and link to this.

[sebastian-meyer]

I added the label. Could you please give a estimate of the cost for this to be considered for the development fund?

[csidirop]

Updated Issue with estimated costs.

[stweil]

Would it be interesting to apply for a Google grant (https://developers.google.com/season-of-docs)?

[sebastian-meyer]

Votes: 3