problems / suggestions / open questions

Session II: feedback

Communication:

Documentation has improved. This is currently not being communicated enough. There are still people with (outdated) opinion that documentation is not good and not useful. They never look in the documentation, so their opinion will not change. Suggestions:
- Mention documentation in newsletter to association members
- some of the changes had not been transparent enough in the past. The communication about infrastructure change was good, though. Communicate changes more.

Migration

contribution

Make it easier to mark a problem on current page
- e.g. this page is outdated
- on other systems, it is possible to mark a line and write a comment directly on the page, (see OpenStreetMap docs)
make it easier to find open issues, possible tasks, things to do
Question: how to make changes now for TYPO3 10? (how to branch out for unreleased versions)
Make it easier to find, how to contribute, e.g. put a clickable question mark (? or i) next to „Edit me on GitHub“ and link to https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingDocsOfficial/GithubMethod.html
make it possible to contribute to the docs from the backend (with an easy workflow)
find a way to automatically create screenshots from backend for each new release of a manual (this would be useful for manuals with lots of screenshots)

usability

it‘s considered weird that typo3.org / docs.typo3.org is separate (good: there is now a „documentation“ button on horizontal menu typo3.org)
create better concept for context sensitive help in backend, doc sysext and official documentation. Also, link to official documentation from backend
search
- search: only in one manual: is confusing
- missing search on homepage is confusing
version selector: not intuitively known to everyone

tools

markdown was mentioned again as easier to use
Is there a tool for live preview? We are currently not aware of preview for reST in PhpStorm. Rendering locally is time consuming. No Wysiwyg or live preview.
Workflow is not non-techi friendly. Vision: easier contributions for non techis. Some agencies have editors. They might contribute more.

content

api.typo3.org is useful and used by several people
Changelog: confusing that some of it is in official docs and in changelog
- create a clear concept how to handle this, how to update main docs
- suggestion: add a field in changelog to specify where changelog should go in main doc
TYPO3 Explaned: missing: main parts of core with images
TCA ref: incomplete, select fields?

Session 3: extension documentation

example extension manual: use structure from sysext „form“, e.g. Tutorial in for editors, quick start
old extension docs: there are still installations with old TYPO3 versions and old extensions. The documentation will disappear. Make old extension documenation available, but don‘t index it in search engines,e.g.
- <meta name="robots" content="index, follow, unavailable_after: 18-Dec-2015 21:44:42 GMT " />