[oi-dev] OI User documentation

[Michael Kruger]

On 12/25/2015 11:10 AM, Aurélien Larcher wrote:
> Hello Michael,
> welcome !
> Thanks for the kind offer, this is great !
> As Nikola pointed in his email setting up a repository and contribution
> guidelines for the existing documentation is an important task.
> I am not sure it is the most efficient way to provide "hands-on"
> documentation though and may be tedious.

Hi Aurelien, Thank you for the welcome.

I agree getting docs into some kind of version control would be very 
helpful. I've previously worked with subversion, but would be more 
inclined to learn how to use GIT.


> Following my previous comment, something to consider is to improve the
> OpenIndiana Handbook:
>
> http://wiki.openindiana.org/oi/OpenIndiana+Handbook
>
> The aspect to consider are not only expanding the content but also using
> a revision control system as well as improving readability.
>
> There are many other blog posts and spread out wiki pages out there:
> consolidating them little by little in one handbook like the *BSDs do
> would be very useful to help newcomers.

Yes, I would agree working on the wiki and handbook would be important. 
After all, these are the very first things someone sees when vising the 
OI website.

>
> One could also consider feeding www.openindiana.org
> <http://www.openindiana.org> with posts to highlight administration
> tasks that may be specific to OI/illumos or emphasize on a change of
> behaviour (creation of ZFS dataset for each user directory, the change
> of sysidtool, ).
> Expanded version of these posts could be later integrated to the handbook.
>
> In any case I think one should be pragmatic and iterate nicely through
> reachable goals.
> Priority IMHO should be on information that allow people to
> contribute/report better and changes affecting the administration on
> Hipster.
> Best regards,
>
> Aurelien
>

I agree 100% on everything you have said. The only way to approach this 
task is by focusing on what can be most realistically achieved. Guidance 
for reporting and contributing is very important as well.

Michael