[oi-dev] Updated OpenIndiana FAQ (3rd draft)

[Michael Kruger]

On 02/10/2016 06:14 AM, Alexander Pyhalov wrote:
> Hi. I have several notices.
>
> "Some notable features of OpenSolaris were the introduction of the all
> familiar GNOME desktop, GNU userland tools, and a new network based
> package manager (IPS)"
> It seems comma before "and" is not necessary, but I'm not a native speaker.
>
> In Feature/Description table some descriptions could be a bit expanded.
> For non-Solaris user descriptions "Service Management Facility" and
> "Fault Management Architecture" say nothing. At least there should be
> links to documentation, wiki or wikipedia.
>
> I'd avoid speaking about 32-bit support. It seems we are going to nuke
> it in future, and in immediate future more and more 64-bit-only
> applications will appear. One old good example is qemu-kvm.
>
> Adam, can we host
> http://www.linuxtopia.org/online_books/opensolaris_2008/index.html on OI
> infrastructure? Referencing to linuxtopia site seems strange.
>
> "Utilities maintenance - pkg[5]". Link seems to be broken. I think this
> item needs brief clarification.
>
> "As illumos is not itself a distribution, OpenIndiana combines
> illumos-gate with OpenIndiana derived oi-userland"
> I think something is wrong with this sentence.
>
> "At this time, the following distributions are known to support the
> SPARC platform:.."
> I think it would be good to reorganize the list in alphabetic order.

Hi Alexander,

I've applied all the edits you suggested and tossed an updated copy out 
on Github Gist: https://gist.github.com/makruger/83209277d6382c01c534

The creole markup rendering is not quite perfect (a few extra ** here 
and there), but github has rendered it mostly correct.

As for hosting the 2009.06 docs, I suppose we could do it on 
openindiana.org, but will we (those working on the docs) be able to 
easily update them there?

e.g. will we be able to obtain FTP access to an upload directory so the 
content can be updated as the documentation project progresses along? If 
not, then perhaps hosting the docs on github pages might provide better 
access to the doc team.

Ideally what I'd really like to see happen is the conversion of the 
solbook xml to asciidoc and import all the OpenSolaris books into github 
in that particular text markup format. I'd like to do the same with the 
handbook, FAQ, and anything else I am working on as well.

Solbook and docbook aren't much fun to work with, whereas ascidoc is 
plainly readable. And using the ruby acscidoctor toolkit, it produces 
some very nice HTML5 output, as well as PDF and EPUBS too.

After playing around a bit with both python based Sphinx and ruby based 
Ascidoctor, I think the later is the way to go. Ascidoctor installs fine 
on Hipster as a ruby gem (yes even with our ancient ruby 1.9).

If the proposed github doc repo could be configured with a commit hook 
to convert the docs and push them to github pages, then we'd have a 
fully automated (and might I also say very modern) documentation 
toolchain. This would really lower the bar for those working on the docs 
and mean less fuss for everyone involved. One would just need to 
understand how to use GIT and how to write docs in ASCIIDOC using the 
text editor of their choice.

Michael