[oi-dev] OI User documentation

[Nikola M]

On 12/25/15 10:10 PM, Michael Kruger wrote:
> On 12/25/2015 02:02 PM, Nikola M wrote:
>
>> One can not replace big documentation with the Wiki
>> and one can not replace Wiki's usability and versatility with
>> XML/ODT/PDF documentation
>
> Once there are more contributors, then taking on larger projects (such 
> as updating the OpenSolaris documentation) could be considered.

I think it is proven to be failed approach to wait for contributors to 
appear. Most likely it never happens without existing people working on 
something and including new ones into it.

>
> I think for now simply getting the OpenSolaris docs (as they currently 
> exist) into version control and placing links on openindiana.org to 
> the GIT repo, would be a good place to start. We'll just need to make 
> clear there are some difference between the docs and current code. We 
> could even go a step further and ask the community for assistance in 
> pointing out those differences so they can be properly documented.

I think that linking web site directly to Wiki can have consequences 
(where some level of linkage must be present), where Wiki needs to have 
flexibility to change and web site needs to have flexibility to change.

Increasing community paticipation can best be done by _Releasing_ OI in 
supportable release so technical work has priority over docs anyway.

* If there are ideas how to improve participation, there are bug reports 
for improvements,
ability to write about that on Wiki itself, and discussing in separate
new oi-docs or oi-advocacy mailing lists.

I don't agree that stopping docs has anything to do with continuing Wiki,
I am also afraid of moves on Wiki side that could destroy search indexes .
Wiki is relatively good in it's shape and preence right now, needs new 
texts and not making it in such different way that it is unrecognizable 
to also current users.

I also think that any renewal projects on OI needs to be public and not 
behind closed doors and just one that pops up with no discussion and 
preparation of community and that includes off-list consultations.

* I support putting docs into versioning, like I originally proposed, 
and think that putting documentation in version control on OI servers is 
good place to start, including new topic on Wiki, that explains how to 
build it and with an article on OI web page about that, that could then 
go to openindiana-discuss mailing list for ask for contribution.

About blog posts, maybe having your own private blog that could have 
articles re-published on OI blog is the best option. Peopel can write 
all sort of things, but only those good enough and passign editorial 
decision would end up on Oi's blog. What do you think?