2018-01-14, 08:12 PM
I have seen multiple previous posts discussing an issue with updates to HelpDoc content done in AdminCP not showing up in the document displayed in the Help section. That issue has been labeled as a "bug". After running into that "bug" myself, I spent a day digging around. This is a report on what I learned. Since this has been brought up in multiple prefvious posts, I thought a single new thread was the best way to respond. I also am responding under General, although some of this contents applies to Development and Translations.
To those who have labeled this issue as a "bug", I agree but it is a bug in design, not coding. The complication designers were faced with was the mixed nature of help documents. Should they reside external to the database in files, easily moved around independent of the myBB system? Or are they like posts in a forum that reside within the database. Further complicating the matter, for pre-defined documents, how does multi-language support get implemented?
For version 1.8, a mixed strategy was developed. Document content resides in the database. The file "install/resources/mysql_db_inserts.php loads the database at the time of installatiion the "predefined" help documents. Using AdminCP, those documents can be modified and others added, the content loading into the database. But that creates an issue with the pre-defined documents for use in "other" languages. To accomodate that, if an alternative version of a document is defined in inc/languages/{language}/*help*.lang.php files, the content of those files is used (for searches and display) instead of the content in the database. Such files are installed for English, so for the predefined documents, the content found in the help file is used instead of the content in the database (which is the content seen in AdminCP). While I understand the complexity of the need and the rational for the design strategy, IMHO it is a poor design that leads to user confusion.
While I can see a more substantial redesign, a fairly simple alternative design would address the language translation issue and also eliminate the confusion created with having dual copies of the document. To some extent, my solution returns to a concept from version 1.6. In AdminCP, one would specify if a document is stored "internally" (in the database) or "externally" (in a file). Each document would have an AdminCP field to specify a document in which the Help Document content would be defined. If that field is left blank the document would be stored internally. If that option is exercised, the content from the specified file is displayed in AdminCP, used in searches, and in the display of the document. Any changes in AdminCP are applied to the file (a bit tricky due to the added complexity of the file structure, but doable). If the option is not exercised, content from the database is used. This solution allows for pre-loaded documents and implementation of translated documents. It also gives the administrator flexibilty in mapping document content into files. All the Help documents can be loaded into a single file, or one could have a separate file for each document, or anything in-between. Depending on circumstances, each solution has merit. It also gives the option of Help Document files residing outside the normal MyBB directory tree, a sometimes useful option for Help documents customized for a particular community. (There are details to be worked out, but that is overall design.)
To those who have labeled this issue as a "bug", I agree but it is a bug in design, not coding. The complication designers were faced with was the mixed nature of help documents. Should they reside external to the database in files, easily moved around independent of the myBB system? Or are they like posts in a forum that reside within the database. Further complicating the matter, for pre-defined documents, how does multi-language support get implemented?
For version 1.8, a mixed strategy was developed. Document content resides in the database. The file "install/resources/mysql_db_inserts.php loads the database at the time of installatiion the "predefined" help documents. Using AdminCP, those documents can be modified and others added, the content loading into the database. But that creates an issue with the pre-defined documents for use in "other" languages. To accomodate that, if an alternative version of a document is defined in inc/languages/{language}/*help*.lang.php files, the content of those files is used (for searches and display) instead of the content in the database. Such files are installed for English, so for the predefined documents, the content found in the help file is used instead of the content in the database (which is the content seen in AdminCP). While I understand the complexity of the need and the rational for the design strategy, IMHO it is a poor design that leads to user confusion.
While I can see a more substantial redesign, a fairly simple alternative design would address the language translation issue and also eliminate the confusion created with having dual copies of the document. To some extent, my solution returns to a concept from version 1.6. In AdminCP, one would specify if a document is stored "internally" (in the database) or "externally" (in a file). Each document would have an AdminCP field to specify a document in which the Help Document content would be defined. If that field is left blank the document would be stored internally. If that option is exercised, the content from the specified file is displayed in AdminCP, used in searches, and in the display of the document. Any changes in AdminCP are applied to the file (a bit tricky due to the added complexity of the file structure, but doable). If the option is not exercised, content from the database is used. This solution allows for pre-loaded documents and implementation of translated documents. It also gives the administrator flexibilty in mapping document content into files. All the Help documents can be loaded into a single file, or one could have a separate file for each document, or anything in-between. Depending on circumstances, each solution has merit. It also gives the option of Help Document files residing outside the normal MyBB directory tree, a sometimes useful option for Help documents customized for a particular community. (There are details to be worked out, but that is overall design.)