[oi-dev] Call for contributors: New OpenIndiana documentation

[Aurélien Larcher]

> "At this point a member of the OpenIndiana Project docs team will review
> your changes."
> - This is what I was actually afraid of. Nothing goes past check of
> those who actually wrote it and mandate what stays in it and don't? So I
> don't suppose changes will be easy to go through.
>

I think the idea is to actually make it easier to contribute: people may
want feedback before pushing content and feel uncomfortable to do so
otherwise.
The pull-request system allows to reviewing changes and get such feedback,
therefore I see it as an improvement.

>
> Real docs  are actually not suppose to be easy to go through with
> changes without review, yet I don't get any info who actually reviewed
> current articles in preparation before launching it.
>

For the current content you can find a list of people involved in the
README of the OpenIndiana oi-docs repository:

https://github.com/OpenIndiana/oi-docs

Alexander and Adam also reviewed the content and I gave some minor feedback.

There are two "teams" in the Github OpenIndiana organization, "Developers"
and "Docs" with appropriate credentials on the repositories.
People involved consist basically of a subset of these teams.


> I think I am pretty much well equipped myself to review them actually so
> I am here available for that.
>

Great!


> "Hosted by the OpenIndiana Documentation Team."
> I don't understand why docs site is not  part of openindina.org styling,
> and represented as separate site.
>

Styling is something that we should discuss. I am actually in the mood for
a refresh of the website and docs styles altogether.


> What is the so called 'docs team' that is supposedly 'hosting'
> Openindiana site (shouldn't openindiana site be hosted by openindiana
> itself and not third party?)
>

The docs team is the Github team, the "hosting" wording is perhaps
misleading.


>
> Actually that site looks like replacing many contents of Openindiana.org
> site itself, too so I am pretty much fully confused of the need for it's
> existence in such form.
> Many parts of it looks better fitting on openindiana.org site itself and
> Wiki (or are just repeating the contents), while truly some of it is
> better left on separate place.
>

I am not sure about that... To me the website should serve rather dynamic
content (news, announcement, ...) and provide entry points to more
substantial documentation. You can see the website as the headlines and a
table of contents with introductory contents: a frontend basically.
Some level of duplication is expected as information presented briefly on
the website may be extended in the user documentation and on the wiki.


> So I recommend for www.openindiana.org site integration, both with style
> and look and feel and to distingush that not everything that comes to
> the mind has a place to be put in Documentation, but on Wiki.
>

The style is something that is already under consideration.
At least we discussed it since Spring.

About the Wiki, see the note below: this is something we already discussed
and the "work in progress" part of OpenIndiana Docs includes refining its
perimeter.


>
> One don't need to learn nor use Git nor make accounts on separate sites,
> if using Openindiana Wiki.
> Another problem is actually depending on Github and organizing hierarchy
> of "pasting issue" there instead on openindiana infrastructure,
> therefore creating separate managerial structure and Github is also not
> available to all the countries in the world.
>

I was not aware of this issue.


>
> I think most of these issues could be resolved by doing things more in
> public, on mailing list in preparation, development, planning and
> working period,
> instead of using private mailing lists, private consultations and
> surfacing with what seems unchangeable "already decided" things.
>

As we discussed in the past: you have to start somewhere.
People may come up with proofs of concept and ask for feedback until the
idea has matured enough to be proposed to the community.


>
> You can't decide what stays or leaves Wiki by yourself, that is the
> process of many people.
> I ask not to cannibalize it's content, but to contribute to it.
> I agree on other stands about one not being replacement for another and
> vice-versa.
>

Following from your earlier comments, I asked Adam to add this line so as
to make clear that this project is about *User* documentation and not
*Development* notes but you managed to take it the wrong way ;)


>
>
> If anyone thinks that Docs are easy to be "rolled released" that is
> conflicting with what Documentation is.
> Documentation is refreshed and can relate to the release and Openindiana
> currently does not have releases to refer to.
> Actually easily and  fast streamlining changes to articles, calling it
> documentation, is what should be avoided
> -IF documentation quality is the goal and mistakes are to be avoided.
> There is an alternative of constantly checking and reviewing every
> possible change and that seems time consuming but unavoidable in
> presented model.
>

Considering the available manpower we need a lightweight process, I think
the presented solution is satisfactory for now.


>
>
> _______________________________________________
> oi-dev mailing list
> oi-dev at openindiana.org
> https://openindiana.org/mailman/listinfo/oi-dev
>



-- 
---
Praise the Caffeine embeddings
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://openindiana.org/pipermail/oi-dev/attachments/20161105/c0bbd582/attachment-0005.html>