[oi-dev] OI User documentation

[Nikola M]

On 12/26/15 12:39 AM, Michael Kruger wrote:
> On 12/25/2015 03:40 AM, Nikola M wrote:
>
>> -There was also docs-discuss mailing list that could be continued and
>> made as new one on OI mailing lists for documentation use.
>
> Nice idea, but I doubt we're quite ready for something like that. 
> Perhaps once DOC talk begin to detract from DEV talk, then it could be 
> moved to it's own ML.

I feel like that oi-dev should not be filled with documentation talk and 
every subproject needs it's place.
We used to have numerous mailing lists for OI,but somehow one day they 
were all removed from visibility and only oi-dev , openindiana-discuss 
and openindiana-announce (with no recent announcements) left:

oi-infra, oi-bugs-team, oi-Caiman-team, oi-G11n-team, oi-Jds-team, 
oi-NewDevs, oi-Pkg-team, oi-Sfw-team, oi-Userland-team, oi-Xnv-team, 
oiac-discuss, Pkgbuild-announce , but they vanished form visibility 
without much posting on them, but also with no explanation.

Having separate mailing list needed, because people also express wanting 
to have separate web-like interface to mailing lists and separating 
topics helps it having nicer distingushed areas, pushing sub-projects 
forward with having interested people on it. It also goes further with 
idea of registering new OI users and let them selecting their areas of 
contribution with a few clicks, that includes mailing lists of interest.

>> -I suggest to start by making new Openindiana wiki page, describing
>> digested manuals and procedures of managing, editing and compiling
>> documentation source.
>
> Looks to me like we would either have to resurrect the old process or 
> develop a new process model. In any case, this would likely need to be 
> secondary to polishing up the Wiki itself. Once the lawn is mowed and 
> the fence painted, perhaps we'll have more people stopping by to 
> assist with larger tasks such as this.

I vote for resurrecting old process because atm documentation from 
Opensolaris we have requires it to build in distributable html and PDF 
formats, so it is more or less technical requirements.
Conclusions, and detailed manula how to proceed with making 
documentation out of it can end up on OI Wiki page, and that would also 
help other illumos distributions to keep up.

I would keep Wiki issues and dicumentation issues separate.
Once we have ability to turn refreshed XML docs in html and PDF and 
publish them on OI site,
then it would be time for not only re-linking site itself but also to 
integrate Wiki content into documentation, too.
Wiki is and should be current and docs project can take several months 
to grow to the current state of things with illumos/OI.

About mowing lawn on Wiki, there needs to be path of upgrading wiki that 
is non-destructive.
In infrastructure side of wiki, there is need for maintaining snapshots 
of it's state
and the most important, Old docs that are already indexed need to have 
aether their older content still available , together with links to 
refreshed pages ,
or that their outside links already indexed on Web crawlers not changed.
Anyway it is of most importance that when something indexed on Google or 
DuckDuckgo or something pops up in search result, Oi wiki responds with 
current page and with posibility to read also older state of pages.

Detailed ideas about Wiki renewal etc, should be discussed further and 
that is also one more reason to have separate oi-docs mailing list.

>
>> 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.
>
>
> Is the Redmine wiki currently using Mecurial?

I have some but not complete view how Oi infrastructure works behind 
scenes, except it is all in Zones on Entic.net. Maybe it is one more 
thing to be documented on Wiki?