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

[Nikola M]

On 05/ 5/16 04:43 PM, Aurélien Larcher wrote:
> Wiki is much more appropriate space for writing articles like those Michael
>> is writing.
>>
>> People writing articles should not be forced to use github and also Wiki
>> articles are instantly visible on site and could be edited by existing
>> people and there is also space on personal blogs for random articles that
>> could be integrated after re-visioning them.
>>

Let's look at it as personal web page/blog and one of many sources of 
writings on the web in general.

Process with writing articles goes like this:
You write article on your blog, whatever -> It goes on Wiki -> It spends 
some time there baking -> Ends up in edited updated XML documentation.
That is what makes sense, that articles on Wiki are always current, that 
articles are edited and checked on openindiana.org , following OI 
hipster changes, while renewed docs are following OI snapshots.

> People will not be forced to use Github and they are not mutually exclusive.
> See it as a way to consolidate existing documentation fed from wikis and
> blogs.

Not accepting "authority" of someone's private Github repo and I 
generally see it as trolling OI at big scale.

Documentation will surely not going to be "consolidated" through third 
party remotely-controlled sites, outside openindiana.org.
I surely care for people's privacy when contacting OI, while doing it 
with third-party sites it is not caring for.

Don't attempt to avoid Wiki, and openinidiana.org , and any decision 
process for OI, and replace existing documentation, renewed docs and 
newly added Wiki articles with some patting in the dark, that will 
resulting in endlessly unfixable results.
Don't undermine recommendation and guidance provided, refusing real 
documentation as a whole and it's license (I warn docs license is to be 
fully upholded) and contributor agreement process that should not be 
avoided.

> I sometimes write short notes for myself on a Wiki: once they are mature
> enough they could be reviewed and added to the repository as part of the
> Handbook.

"Handbook" is immaturely crafted idea. There is the difference between 
"Manuals", "Cookbooks" and "Blogs" and OS documentation and this is 
neither, it is not short and simple like manual for a Wiki, nor what 
serious docs are supposed to be. It is someone's mutated personal blog 
in a form of Github web page.

Not only that Wiki will not migrate to outside sites (and it's not about 
technical but managerial things and docs things),  and I don't like 
seeing my recommendations being misused in some private project, that is 
_not_ OI docs.

Not to mention the need to have docs baking process and tools for 
building it in-house and not scattered all over the web.