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

[Michael Kruger]

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