[oi-dev] demonstration docs website

[Michael Kruger]

On 05/04/2016 06:52 AM, Alexander Pyhalov wrote:

 > Hi, Michael.
 >
 > Thank you for your work.
 > To move further I think we should consider several questions...
 >
 > 1) Someone should look through the docs... So , reviewers are welcome.
 > Have you changed "OpenSolaris Redistributable Books" in any way or just
 > created the index and converted them to docbook? How do we mark parts of
 > the books which are not currently actual? How are we going to update
 > them (create new document or mark current document as reviewed)? How
 > http://makruger.github.io/website/pages/docs/handbook.html and
 > http://wiki.openindiana.org/oi/OpenIndiana+Handbook are related? What
 > parts are missing?



The website is composed of 3 separate components:

1) The Awestruct web framework

And the contents of 2 GitHub repositories:

2) https://github.com/makruger/openindiana-docs
3) https://github.com/makruger/docs_20090715

The Awestruct framework works with an Asciidoctor plugin to compile 
Asciidoc text markup content pages into HTML5 and then deploys it to a 
gh-pages branch. This branch is published to GitHub pages.

The compiler parses through everything it finds and anything which is 
already compiled (or for which there is no parser) is simply copied over 
without any further processing. The main index as well as header/footer 
layouts, etc., are composed in HAML (but can also include snippets of HTML).

The 2 GitHub repositories are not configured as submodules, but going 
forward they probably should be, or alternately things could remain as 
they are and inclusive of it all.

The openindiana-docs repository consists of the FAQ I previously worked 
on as well as a skeleton for an updated handbook. It also includes 
several informal 'work products' containing notes and guidance for 
anyone working on the docs project. Some of these work products could be 
used in the creation of other documents, others are better reserved for 
reference use only.

As for the handbook, I never envisioned it becoming as comprehensive the 
OSOL books, but rather be used as a supplement to them. Call it a guide 
for new users wanting to quickly get up to speed with the operating system.

The docs_20090715 repository contains the redistributable books. Here I 
simply extracted the zipfile (which already contained compiled HTML 
along with the raw XML sources) and wrote several index pages which 
linked it all together.

These books are as originally released without any further editing. I do 
not yet have a formal process for updating the books. Up until this 
point my only concern has been to host them as they are and develop a 
process for updating them at a later date.



 > 2) What is the process of contribution, how site is generated? What
 > tools are used to work on the docs ( asciidoctor + git ?)?



At this time the site is manually generated. Though in the future it 
could be automated using Travis-CI.

For those interested in helping with the development of the website 
itself, Awestruct can be run locally in development mode. This requires 
a Ruby environment, although this can be simplified in the future by 
using Gradle.

For those who wish to contribute to new or existing content, all that is 
required is a text editor. I use VIM along with an asciidoc VIM plugin. 
There is also an Asciidoctor IDE by the name of AsciidocFX. The IDE uses 
an Atom like text editor along with a live preview of the parsed text.

For those who wish to use VIM, there is an Asciidoctor plugin available 
for firefox (and Chrome as well) which can be used to parse the document 
and provide a close approximation of it's final rendered form.

Content is written using Asciidoc text markup (or more specifically the 
enhanced Asciidoctor version of it).

In either use case (content creation or website development), 
contributors would fork the repository and submit a pull request to have 
their changes incorporated. Someone (most likely me or anyone else who 
wishes to help) would review and merge the changes.

As for linking new documents with site menus, this is a manual process, 
but could be simplified by using TOC pages and adding and simply adding 
a new line item for the additional document.



 > 3) How do you propose to incorporate documentation site in current OI
 > web site? How do you suggest to consider what articles should live on
 > the wiki, which - on documentation site? How these two sites are going
 > to be related?



These are very good questions. I think initially we can provide a menu 
option on word press to redirect users to the docs site. Other pages may 
contain references residing on the docs site much as we do today with 
the Wiki.

As for deciding what goes where, unfortunately I do not yet have an 
answer. My inspiration for this project has been the Jenkins project who 
as far as I know have retained their Wiki. We could probably look to 
them for an answer to this question.

Michael