Fri. 15th December, 2006
Documentation is a great thing - if you have it. Fortunately many developers provide you with a nice manual together with their extension. Every night these documents are transformed into different output formats, including HTML which lets you read the manual online. But sometimes all see is a red colored message: "Not available". If you asked yourself why some documentation is not available and other manuals are, you now get your question answered. For each extension which is uploaded from now on a little report will be created. It contains detailed information about problems which arose during the rendering process. This protocol can be viewed online at typo3.org and can help the extension author to solve problems with the structure of his manual. All you have to do is click at the little "Why?" link next to the Not available message. The number one reason for unavailable documentation is not a technical one - in most cases a manual just doesn't exist. But unfortunately not all problems can be detected that easily. The Open Office documents are transformed to DocBook as an intermediate format and from that basis into other formats such as HTML or (in the future) PDF. Due to the XSL transformations which do the conversions the whole process is a bit susceptible to structural changes in the source document. Therefore the most important aspect when creating a manual is to use the official manual template and structure the document with the correct heading levels and paragraph templates. Hopefully this new TER feature will help you to spot errors in your extension manuals. If you're still stuck, you're welcome to ask for help in the DocTeam or the TYPO3.org team mailing list.
This is a companion discussion topic for the original entry at https://typo3.org/article/manual-not-available-why/