About OpenIndiana Docs
This website and its content uses a number of different technologies:
- Page content written in the Markdown text markup language.
- Text markup transformed to HTML using the MkDocs documentation framework/static site generator.
- Website styled using the Bootstrap CSS framework (more specifically the Bootswatch Spacelab theme).
- Source code hosted in a GitHub repository.
- Website hosted on GitHub Pages
History of OpenIndiana Docs
The current documentation revitalization effort began in late 2015. For some time the project recognized it needed to do a better job of organizing and presenting end user documentation. Just as important, it also recognized how documentation needed to more accurately follow the development state of OpenIndiana Hipster.
The docs team began by looking at:
- The current state of the OpenIndiana project's documentation.
- The methods and toolkits used to create past and present documentation.
- How other projects where approaching their systems documentation efforts.
Much of the migration from the previous Confluence based Wiki was completed in 2019. In 2021 the previous Wiki had to been taken offline due to vulnerabilities in the Confluence software it used.
Documentation revitalization effort goals
As a result of the aforementioned exercises, the team established the following goals:
- Increase participation and lower the bar of entry by simplifying the documentation process.
- Provide well organized, technically accurate information in an aesthetically pleasing way.
- Treat docs like code (for example: using version control, continuous integration, etc.)
- Migrate all existing and future documentation to a simple text based markup.
- Deploy documentation via a static website generator.
- Employ a dynamic mobile friendly CSS framework.
To this end, the team looked at several documentation oriented static site generators and selected MkDocs for its simplicity, ease of use, and professional quality output.
Using the OpenIndiana Docs website
The OI-DOCS website can be navigated in several ways:
- Using the drop down menus from the top navigation bar.
- Clicking the Next and Previous buttons.
- Using the table of contents found on the left or top side of each page.
- Using the full text search function found in the top navigation bar.
NOTE:
Contributing to OpenIndiana Docs
First and foremost, we understand using development tools and techniques to write end user documentation is not for everyone. For this reason, we're happy to accept your contribution in any format you wish to provide.
After receiving your submission, we will review the document for conversion to markdown and subsequent incorporation into OpenIndiana Docs. Contributions may be submitted in plain text, .doc, .docx, .odt, html, xml, latex, pdf, GitHub Gist, etc.
In summary, if you believe your contribution would be helpful to the greater OpenIndiana community, we'll be willing to review it. For further information, please see the contribution pages found elsewhere on this site.
Providing feedback
Community feedback is critical to the growth and development of the OpenIndiana Docs website.
To make a suggestion or report a problem with a document, please make your request by submitting a Github issue.
The docs team can be reached via email: docs at openindiana.org.
You may also inquire via IRC:
Created: 2016-06-06 02:47:56