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

[Till Wegmüller]

Hi Michael

First of thank you for your hard work on the Documentation thus far.

On 04.05.2016 07:00, Michael Kruger wrote:
> This leads me to suggest there should be an OpenIndiana 'Code of 
> Conduct' to help reign in people with troublesome behaviors
Here i would like to input a bit of my experiece as a Kaopilot Student. 
Kaospilots is a Business shool which works with community based 
organization models and frameworks. Thus we also study communities in a 
great detail. Ranging from 3500 Year old traditions to modern day 
Communities.

What I have learned from that, is that if you "reign in people with 
troublesome behaviours" you will only cause more hostility.
The best cause of action I find is to make people aware what their 
bevahiour causes. This gives those people the freedom to rethink their 
actions and handle how they see fit.
This also happened in this case. And that person rephrased their mail to 
be more objective.

If we want to write down some general rules about what we would like 
people to do when bringing critique about work done is another topic.
But what i have learned in the 7 months working in this way is, it is 
hard to give objective and nice formulated feedback if you have not 
trained it.
So whatever we write down. It does not work if people do not commit to it.


> 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. 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.
>
Please make people aware of this as soon as you see it. I was not aware 
of how the wiki behaves on tablet devices.
Also you have a view of things that lang time project memebers do not have.
We would realy like to see your view. Your view is a resource to reach 
more people with similar views on documentation.

Thank you for sharing your View.

> 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. 
On this point i agree.

I would like to aks the people from the community to share what they 
think is a documentation.
Or what they think a documentation requires.
And what they want to be the outcome of this documentation project.

Greetings Till