[oi-dev] OI User documentation

[Michael Kruger]

On 12/25/2015 03:40 AM, Nikola M wrote:
> 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.
>
>
>
> _______________________________________________
> oi-dev mailing list
> oi-dev at openindiana.org
> http://openindiana.org/mailman/listinfo/oi-dev


Thank you for gathering all this information and putting it into one 
place. Yesterday I too looked at Archive.org. We both read mostly the 
same information.

Given how this documentation project is literally rising from the ashes 
of OpenSolaris, perhaps OpenIndiana should be renamed PheonixOS? It 
seems rather fitting as it describes the condition of the OI project as 
a whole, and would also be consistent with the naming convention of all 
the other Illumos derived distros. Just some food for thought;-)

Because of the length of your post to the ML, I will try to break up my 
replies into bite sized responses so it does not all become TL;DR.

Michael