[oi-dev] Call for contributors: New OpenIndiana documentation

[Nikola M]

On 11/ 4/16 03:31 PM, Adam Števko wrote:
> Hello folks,
>
> After severals months of Michael’s hard work, we are glad to present a future basis for new OpenIndiana documentation. The documentation can be found at http://docs.openindiana.org. 
>
> Michael tried to make the contribution barrier as low as possible, so here are couple of things:
>
>     • Documentation fixes/additions/removals all leverage the Github pull request (PR) system.
>     • Every PR is automatically built and the result of each build is marked in the PR menu. With this, you will know in a matter of minutes whether the change you made is mergeable and satisfies our checks.
>     • After a PR is merged, the change is automatically built and deployed to http://docs.openindiana.org
>
> To begin contributing, the process is described in great detail at http://docs.openindiana.org/contrib/getting-started/. Contributing directly from OI is fully supported (either follow steps in the guide or "pkg install mkdocs"). You may also contribute from non-OI operating systems. 

First of all I recognize positive and altogether nicely put announcement
text , so I would also ask that points that I would be reflecting to and
putting light on (enev if possibly not putted in so nicely) be seen with
an equal amount of positivity.
Reporting bugs and problems and discussing them is the normal thing and
one won't work without another. :)

"At this point a member of the OpenIndiana Project docs team will review
your changes."
- This is what I was actually afraid of. Nothing goes past check of
those who actually wrote it and mandate what stays in it and don't? So I
don't suppose changes will be easy to go through.

Real docs  are actually not suppose to be easy to go through with
changes without review, yet I don't get any info who actually reviewed
current articles in preparation before launching it.

I think I am pretty much well equipped myself to review them actually so
I am here available for that.

"Hosted by the OpenIndiana Documentation Team."
I don't understand why docs site is not  part of openindina.org styling,
and represented as separate site.
What is the so called 'docs team' that is supposedly 'hosting'
Openindiana site (shouldn't openindiana site be hosted by openindiana
itself and not third party?)

Actually that site looks like replacing many contents of Openindian.org
site itself, too so I am pretty much fully confused of the need for it's
existence in such form.
Many parts of it looks better fitting on openindiana.org site itself and
Wiki (or are just repeating the contents), while truly some of it is
better left on separate place.
So I recommend for www.openindiana.org site integration, both with style
and look and feel and to distingush that not everything that comes to
the mind has a place to be put in Documentation, but on Wiki.

One don't need to learn nor use Git nor make accounts on separate sites,
if using Openindiana Wiki.
Another problem is actually depending on Github and organizing hierarchy
of "pasting issue" there instead on openindiana infrastructure,
therefore creating separate managerial structure and Github is also not
available to all the countries in the world.

I think most of these issues could be resolved by doing things more in
public, on mailing list in preparation, development, planning and
working period,
instead of using private mailing lists, private consultations and
surfacing with what seems unchangeable "already decided" things.

> I would also like to warn people that you still have to consider this project as work in progress and it does not serve as Wiki replacement. The longterm plan of this project is to serve as the end user documentation and fulfill a role within the OI community much as the FreeBSD handbook does for the FreeBSD community. 
> The OpenIndiana wiki has a lot of content, but a huge amount of it is outdated and not relevant any more. However, this will be solved in the future by doing another call for participants. Notes related to the OpenIndiana development are to stay on our wiki in the future.

You can't decide what stays or leaves Wiki by yourself, that is the
process of many people.
I ask not to cannibalize it's content, but to contribute to it.
I agree on other stands about one not being replacement for another and
vice-versa.

> Those who have used the FreeBSD handbook will know what I’m talking about. 

FreBSD is competitive OS with different non-copyleft philosophy. Anyone
liking FreeBSD is free to use it, Oi is not FreeBSD. I consider not
looking over the fence as the possibility of doing things better then
anyone else.
OI does not depend on FreeBSD, not even for the philosophy including
rolling-release model.

If anyone thinks that Docs are easy to be "rolled released" that is
conflicting with what Documentation is.
Documentation is refreshed and can relate to the release and Openindiana
currently does not have releases to refer to.
Actually easily and  fast streamlining changes to articles, calling it
documentation, is what should be avoided
-IF documentation quality is the goal and mistakes are to be avoided.
There is an alternative of constantly checking and reviewing every
possible change and that seems time consuming but unavoidable in
presented model.