[OpenIndiana-discuss] OpenIndiana Docs (proof of concept) - What is it all about?

[the outsider]

Hi Michael,

I admire your dedication, knowledge and your love for OpenIndiana. 
But imho I think you are too late. OpenIndiana is almost near extinction. 

I have been on the mailing lists quite some time and questions and responses
are declining rapidly. 
In my opinion this is caused by the separation of OI users in 2 groups: the
PC/laptop OS users and the server users. 
Too many times there have been devastating discussions about getting Firefox
ready on OI and if or not one should bake pizza's to create the code. While
on the other hand updates for every day used server programs are not
available. 

For server usage in a professional way OI is lacking more and more security
updates, only if you use the hipster or hipster2 or no wait the
hipster-hipster version. (I lost track of it) 
I have long tried to use OI as a professional server but in December I
installed SmartOS and I went from hell to heaven. 
I went from 7 days half-baked "make" "configure" "install" search and
destroy deployment nightmares to 15 minutes deployment. 

There is only one big problem with SmartOS and that it has opensource
sourced by a commercial company. So there can always be a point in time
where the opensource will be closed or unreachable. 
But at this moment Joyent flows there advantages back to the Illumos core.
(http://mail-index.netbsd.org/pkgsrc-users/2016/04/29/msg023314.html) so
even OI should benefit from it. 

So IMHO someone (preferable more than one) should build the bridge between
documentation scattered over illumos, solaris, smartos and Openindiana
websites and creators. 

This is my opinion, no insults intended. 

Br,

Roel

-----Oorspronkelijk bericht-----
Van: Michael Kruger [mailto:makruger2000 at gmail.com] 
Verzonden: woensdag 4 mei 2016 7:00
Aan: OpenIndiana Developer mailing list <oi-dev at openindiana.org>; Discussion
list for OpenIndiana <openindiana-discuss at openindiana.org>
Onderwerp: [OpenIndiana-discuss] OpenIndiana Docs (proof of concept) - What
is it all about?

Now that the dust has settled a little bit after my initial presentation,
perhaps I should elaborate a bit about my motivations and intentions in
creating this little proof of concept.

In the responses and discussions that followed, some feathers were ruffled,
and a number of points where raised, many of which could be distilled into
at least 3 distinct themes.

I'll start by talking about the first theme as everything else hinges upon
it.


* Community conduct
* Project visibility
* Proof of concepts

* Version control
* Hosting infrastructure
* Project marketing, SEO

* Existing docs (OSOL Docs)
* Viability/Usability of Wiki
* dlc.openindiana.org/docs
* Documentation Standards (media types, etc.)
* Licensing/Contributer agreements/copyrights, branding etc.


It's now been about 3 months since I volunteered to help the project 
with documentation. I have learned quite a bit and overall it's been 
very interesting. I chose this project because it was very small, needed 
people, and I thought I might be able to make a meaningful difference. I 
still believe that.

So, this is my creative outlet. This is a place where I can express 
myself, learn, try new things, and explore new ideas. It's a place where 
I can (hopefully) make a difference.

Having a creative outlet is very important to me, because in my day job 
I work for a government bureaucracy. There each department is it's own 
little kingdom where nobody shares information or works together. As a 
result, innovation is stifled and dysfunction is pervasive. Even worse, 
most people are unhappy, and everyone complains. But the money is good 
and my commute is very short, so I put up with it all.

Here however, we're all volunteering our time. So I think having an 
atmosphere of acceptance, civility, and respect is extremely important. 
If not, the project will eventually curl up and die.

However, before any of that happens, people may find themselves needing 
to work alone or in small groups specifically and intentionally 
excluding individuals with problematic behaviors. This will occur 
because it's simply not possible to get anything done in an atmosphere 
of hostility, jumping to premature conclusions, or where kvetching is 
the rule of the day.

This leads me to suggest there should be an OpenIndiana 'Code of 
Conduct' to help reign in people with troublesome behaviors. After all, 
such individuals effectively prevent others from achieving anything 
meaningful. The future of the project may very well depend on it.

Having said all of that, let me turn the discussion back to my little 
docs website proof of concept. For starters, it's not a submarine 
project, nor do I intend to apply any kind of licensing which may 
restrict it's reuse in any way. Frankly I could care less how it's 
licensed. I wrote it all for the pure joy of writing. And in the spirit 
of community, it's free and available to all.

As for how it evolved the way it did, there are a number of reasons.

As soon as I joined the project I began looking at the OSOL docs, the 
website, and the wiki, and took notes of my thoughts and observations 
along the way. Those notes are publicly available for anyone to see:

https://github.com/makruger/openindiana-docs

The README describes what's in each document. This is all public and has 
been for quite some time. Again, not a submarine project at all.

So, after looking at the current state of information management, 
several things became clear.

There needed to be a way to:

1) Place documentation under distributed version control.
2) Lower the bar of entry to the documentation process.
3) Make changes and quickly deploy those changes in some kind of 
automated fashion (e.g. continuous integration).
4) Present the documentation in an organized and aesthetically pleasing way.

It's been said that a project lives or dies by it's documentation. 
Whether that's really true or not, I don't know, but the general 
perception for OpenIndiana is it's largely an undocumented project.

The need is there, now it's just a matter of coming up with a workable 
method for addressing the need. Good docs are important. Just as 
important is way the documentation is organized and presented.

This leads me to state the obvious:

The current state of the wiki is quite poor. The content is poorly 
organized, largely outdated, and the navigation menus do not function at 
all on mobile devices (this included tablets). This is a real problem, 
especially if the project expects people to rely on the Wiki as the "go 
to" source of information about the OpenIndiana project.

I can only conclude by saying this is quite unacceptable and something 
better is required. Whether that something better is my little project, 
or something else entirely, that's for the community to decide.

My proposal is on the table and I can only expect it to be fairly judged 
on it's technical merits. It should not however be frontally assaulted 
because it differs from the way things have always been done.

Michael








_______________________________________________
openindiana-discuss mailing list
openindiana-discuss at openindiana.org
http://openindiana.org/mailman/listinfo/openindiana-discuss