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
_______________________________________________
oi-dev mailing list
oi-dev@openindiana.org
http://openindiana.org/mailman/listinfo/oi-dev
