[oi-dev] OI User documentation

[Nikola M]

On 12/24/15 09:40 PM, Michael Kruger wrote:
>
> On 12/22/2015 05:16 PM, Michael Kruger wrote:
>> Hello all,
>>
>> My name is Michael Kruger and I would like to help contribute to the OI
>> project by doing whatever I can towards improving the state of OI's end
>> user documentation. I'm also willing to help with QA testing.
>> ...
>>
>> Currently I am reading my way through the OpenSolaris Bible and thought
>> giving back to the community by writing some OI tutorials and end user
>> documentation would be a great way to help solidify and increase my Unix
>> admin knowledge.
>
>
> Found the official OpenSolaris docs. I think these are open source.
>
> http://files.if.undip.ac.id/index.php?dir=UNIXbox/OpenSolaris
>
> Perhaps we could import them into a GIT repo or something.

That docs-20090715.tar.gz is what I have saved locally to. It has same 
MD5 hash
$ md5sum docs-20090715.tar.gz
ee66ee6ee82cc710c425c8130289a2d2  docs-20090715.tar.gz

I have put it here, too https://mega.nz/#F!PJI2yLAK!B58qhG2jqIffPNtQD9dKqw
for faster download and some docs I found on archive.org, final 
Opensolaris compiled docs in PDFs , licenses and some guidances how to 
compile it form XML.

I still don't know of at least one complete Opensolaris mirror that 
keeps everything i one place including Opensolaris docs (anyone know it, 
don't know if everything is on hg.openindiana.org ?),
but I see this was kind of layout that was on http at the time:
https://web.archive.org/web/20090415222419/http://dlc.sun.com/osol/docs/content/

-There was also docs-discuss mailing list that could be continued and 
made as new one on OI mailing lists for documentation use.

-I suggest to start by making new Openindiana wiki page, describing 
digested manuals and procedures of managing, editing and compiling 
documentation source.


Then there is an issue of putting docs into some versioning process, 
where Openindiana has Mercurial repos on it's servers that resembles 
Sun/Oracle practice.
Having Mercurial and/or GIT locally (possibly with  on Openindiana 
servers has strong benefits to just using Github because at the end all 
sources and final results must be distributed with the releases and it 
makes sense for easy mirroring and distribution.
If it is put on GitHib it again has to be moved to OI servers to there 
is no much merit to keeping it on Github.

Documentation needs decisions weither it will replace "Opensolaris" 
wording with illumos or with Openindiana or both where appropriate.
Also weither docs need to be separated in illumos ones that could be for 
all illumos distributions OS'es to share and contribute and those for 
just Openindiana.

Also to renew information in docs, there needs to be followed everything 
that has changed from the date of latest docs sources (we'll see if 
those are those in that archive or there are newer docs up to 
opensolaris snv_134 in mirrored source repo) ,
till the snv_134 and later in OI's pre-illumos and after illumos time.

Further, compiled Docs usually follow releases and OI still does not 
have supported releases and two branches of development (stalled /dev 
and never-releasing /hipster-2015) have not merged yet,
so I propose to follow docs changes as
- Changes inside Opensolaris till snv_134 and snv_142
- Changes inside Openindiana before illumos inclusion (hopefully there 
would be not much)
- Changes in illumos from it's start till today that reflect illumos docs
- Changes in Openindiana /dev untill OI hipster fork
- Changes in Openindiana hipster from it's birth till today's recent 
changes.

I must also point out that we recently lost fine nice OI hipster changes 
history that was present
in http://hipster.openindiana.org:8080/job/oi-userland/changes
and I don't know how to re-create them to include links to actual code.

Also for some reason I don't understand OI hipster Jenkins build server 
does not distinguish between illumos changes in it's log 
(http://hipster.openindiana.org:8080/job/oi-userland/changes) and 
oi-userland ones.
So it is more difficult to disctinguish and follow what actually changed 
in illumos and what changed in distribution like OI to see it's 
documentation significance.

Hipster actually has very little documentation and comments on changes 
and following mailing list talks on changes (if any) is painful.
OI and Hipster actually needs more people like you in not only 
documenting, but also testing, QA and reporting bugs if not also fixing 
them,
but definatevly needs more steering talks and goal setting for new 
coming developers (needs advocating too) so that things go into Stable, 
supported OI for server and desktop with current docs.

Using Oracle Solaris Docs is unusable from the moment when it's OS/Net 
turned closed or at least not relesing source and even if their docs are 
available in source code and with a public license I doubt it could be 
reused easily, because there are changes on both illumosand Solaris 
side, that are not in each other.
So more painfull and full approach is more likely for refreshing 
Opensolaris docs into current illumos and Openindiana docs.