An initial build of the new documentation site, titled osCommerce Library, has been pushed to Github and aims to replace our existing documentation sites (Confluence and the documentation section on the forum).
This is obviously built on our new framework to allow us to create a site that meets our requirements (integration) and to make writing documentation fun again. The content from the forum documentation section has already been migrated to it and will replace it as soon as the design and navigation has improved. After this the content from Confluence will be migrated over to finally be able to replace that as well.
The documentation content is now written in HTML files with the possibility of using template tags from the new framework to help make it easier writing complex HTML blocks.
The benefits of storing the documentation content in files and not in the database is it makes it really really easy to edit the HTML files in your favourite editor and push the changes to Github which the server can then pull and use instantly.
At first a Markdown implementation was being developed however the amount of work involved to produce nice looking output was not worth it when HTML could already be used which simplified things a lot. Styling is based on Bootstrap and styles can be customized where appropriate.
The documentation site organizes the documentation content as Books -> Chapters -> Pages. The structure and sort ordering is defined in a json file:
This makes it easy to add, remove, and reorder pages and chapters in a book. Each is identified via a code and to prevent conflicts of duplicate files, the HTML files are named in the following manner:
book_code-chapter_code-page_code.html ("-" separating each section)
This can be seen here:
It might be better to split the long filenames into directories (eg, book_code/chapter_code/page_code.html) so this style may change.
Foreign languages are taken into account so the documentation can be translated into different languages. There is still some hardcoded "en" parts in the source code that will be updated. Please do not start translating as the documentation is outdated. Feel free to translate the release notes though.
The documentation site in its initial and current form can be reached at:
As a side note, this is one of the cool features of the framework where a site can have its own URL. Although http://www.oscommerce.com/index.php?Library would be the original URL, it has its own address defined in the settings and the framework automatically detects this and uses it Some url rewrite magic is still needed though to support multiple languages with /en/, /de/, /fr/, etc.. in the url.
Please note that this is an early build and is still being worked on. The design and navigation will definitely improve and it is also planned to index the documentation content into a database to allow searching.
The flexibility of the new site also allows us to use wkhtmltopdf in backend scripts to produce PDF formats of the documentation to include in releases.
What are the thoughts of the initial code?
Should the HTML filenames be split into directories for a cleaner structure?
Should foreign languages follow the english layout (table of contents) or have their own freestyle layout?
Should a rating or comment system be added?