Re: [oi-dev] demonstration docs website

2016-05-07 Thread Nikola M 

On 05/ 6/16 08:06 PM, WebDawg wrote:

I am starting from the first email because there have been so many
replies and responses to this one and no one has provided anything but
it seems negative feedback to this git site.  I also see very little
contribution to the subject of documentation.

Right now a majority of OpenIndiana docs are on the wiki here:
http://wiki.openindiana.org/oi/OpenIndiana+Wiki+Home

I have never even heard of http://dlc.openindiana.org/docs/ until it
was mentioned a few days ago.


Michael Kruger maliciously requested yesterday that all Opensolaris docs 
be removed from
http://dlc.openindiana.org/docs/ , not telling he requested to host 
expanded .zip with Opensolaris docs as reference, but I requested for 
another Dir with Docs be there for Docs renewal reference.


They are available on and are re-distributible and are available for 
reuse under PDL on:

https://mega.nz/#F!PJI2yLAK!B58qhG2jqIffPNtQD9dKqw

When you unpack them you can read all of them, and you get all the docs 
we have from Opensolaris and there is also application for exporting 
from DocBook XML into HTML and PDF and those are what Openinidana docs 
can build upon, same as illumos was grown form Opensolaris.

Trere are tool on:
https://github.com/rmustacc/illumos-docbooks  under /tools (SolBook Trans)
GUI part needs fixing but in CLI it does the job of making Html and PDF.

We currently have extensive existing "Openindiana handbook" on Oi Wiki 
and it can be extended as needed: 
http://wiki.openindiana.org/oi/OpenIndiana+Handbook


You can propose changes and request Wiki account if you have updates in 
mind.


(unless someone trolls out for them to be removed so he can say they 
"don't exist"..)



___
oi-dev mailing list
oi-dev@openindiana.org
http://openindiana.org/mailman/listinfo/oi-dev

Re: [oi-dev] demonstration docs website

2016-05-06 Thread Aurélien Larcher 
On Fri, May 6, 2016 at 8:06 PM, WebDawg  wrote:

> > Date: Sun, 1 May 2016 00:30:55 -0400
> > From: Michael Kruger 
> > To: OpenIndiana Developer mailing list ,
> > Discussion list for OpenIndiana <
> openindiana-disc...@openindiana.org>
> > Subject: [oi-dev] demonstration docs website
> > Message-ID: <5725867f.9030...@gmail.com>
> > Content-Type: text/plain; charset=utf-8; format=flowed
> >
> > Hello all,
> >
> > Here is a little something I have been working to help showcase
> > documentation for the OpenIndiana project.
> >
> > Currently hosted are:
> >
> > OpenIndiana FAQ (Complete, but still growing and improving)
> > OpenIndiana Handbook (little more than a template at this point)
> > OpenSolaris Books (41 titles from the 2009 redistributable docs release)
> >
> > All of this resides on github, so further evolution of this website and
> > it's content simply follows existing development practices.
> >
> > Here is the URL: http://makruger.github.io/website/
> >
> > Enjoy,
> >
> > Michael
> >
>
> I am starting from the first email because there have been so many
> replies and responses to this one and no one has provided anything but
> it seems negative feedback to this git site.  I also see very little
> contribution to the subject of documentation.
>
> Right now a majority of OpenIndiana docs are on the wiki here:
> http://wiki.openindiana.org/oi/OpenIndiana+Wiki+Home
>
> I have never even heard of http://dlc.openindiana.org/docs/ until it
> was mentioned a few days ago.
>
> I like wiki's.  Personally I use archlinux and they have one of the
> best wiki's I have ever used.  I like wikis because they are so
> dynamic.  It is easy for me to edit, easy for me to fix.
>
> 1) Place documentation under distributed version control.
>
> Not all documentation I think should be under version control.
> Though, documentation created by the people that help create OI I
> think would.  I really think that what you are creating is not a
> documentation site but a new handbook.  Is there a public, updatable,
> handbook right now?
>
> I would keep the wiki AND have this nice handbook.  I really think the
> front facing page should be integrated somewhere branching off of the
> main site to summarize the entirety of the OI documentation structure.
>
> It seems like, with the wiki and handbook approach, you would be
> duplicating work but then lets take a look at this page:
>
> http://wiki.openindiana.org/pages/viewpage.action?pageId=4883847
>
> That page needs updated, it looks like 4k problem has been fixed, or
> possibly not.  Why are people commenting instead of fixing the wiki
> itself?
>
> If you have a handbook that developers can edit simply and quickly
> once a problem has been fixed in OI, is this not better?  Or is this a
> problem solved by man pages?
>
> 2) Lower the bar of entry to the documentation process.
> I do not know why the bar is high right now?  Can you explain this
> more?  Making an account on the wiki is not hard.
> Making an account on git is not hard either but I would like to
> mention that most people are used to editing wikis.
>
> 3) Make changes and quickly deploy those changes in some kind of
> automated fashion (e.g. continuous integration).
> Once again, I already talked about developer -> git docs editing, but
> can you please explain this more?  Wikis are just click and edit.
>
> 4) Present the documentation in an organized and aesthetically pleasing
> way.
>
>  https://makruger.github.io/website/pages/docs/handbook.html does not
> work.  https is broken in your css.
>
> I agree a bit on this.  I do not like Confluence, but it does make for
> a nice looking index layout.  I am really a fan of mediawiki and I do
> not understand why they chose to go with the Atlassian Confluence
> Community License when mediawiki is FOSS.  To each there own and I am
> sure it was thought about.
>
> I like straightforward layouts that do not obfuscate things.  I want
> all the information on one pagenot a million different menus.  One
> large TOC/index and all the text at my fingertips.  i should not need
> a search engine to search a manual.  If I open up a handbook, I want
> the handbook.
>
> Though, if what you have created were to be accepted, you are adding
> more work.  I do not OI has a dev lead or team right now right?  Who
> is going to support it?  The support/work might not be in vain though
> because documentation should support the release.  It is very
> frustrating for users to use an OS and not find the docs they need.
> Or find out dated docs.  Do you think a developer would take time to
> fix docs though when they already have man pages and README's?
>
> If you were to link the docs via github to code changes, every release
> could have its handbook frozen in time/git releases/names for each
> release.  In fact I think this could be a powerful feature if OI ever
> does an LTS release.
>

Actually the

Re: [oi-dev] demonstration docs website

2016-05-06 Thread Aurélien Larcher 
> 1) Place documentation under distributed version control.
>
> Not all documentation I think should be under version control.
> Though, documentation created by the people that help create OI I
> think would.  I really think that what you are creating is not a
> documentation site but a new handbook.  Is there a public, updatable,
> handbook right now?
>
> I would keep the wiki AND have this nice handbook.  I really think the
> front facing page should be integrated somewhere branching off of the
> main site to summarize the entirety of the OI documentation structure.
>
> It seems like, with the wiki and handbook approach, you would be
> duplicating work but then lets take a look at this page:
>
> http://wiki.openindiana.org/pages/viewpage.action?pageId=4883847
>
> That page needs updated, it looks like 4k problem has been fixed, or
> possibly not.  Why are people commenting instead of fixing the wiki
> itself?
>

But I think with this example you are exactly pointing out the fact that
documentation covers different things:
- developer notes
- ephemeral information (i.e workarounds)
- end user documentation (fairly static)
- etc...

So Wiki and Michael's proposal are complementary as they address different
types of documentation and it was never the question to replace the Wiki.
The Wiki does not allow you to generate to different media as it would be
required for the Handbook.


>
> If you have a handbook that developers can edit simply and quickly
> once a problem has been fixed in OI, is this not better?  Or is this a
> problem solved by man pages?
>
> 2) Lower the bar of entry to the documentation process.
> I do not know why the bar is high right now?  Can you explain this
> more?  Making an account on the wiki is not hard.
> Making an account on git is not hard either but I would like to
> mention that most people are used to editing wikis.
>

Ability to ask for review comes to my mind.


>
> 3) Make changes and quickly deploy those changes in some kind of
> automated fashion (e.g. continuous integration).
> Once again, I already talked about developer -> git docs editing, but
> can you please explain this more?  Wikis are just click and edit.
>
> 4) Present the documentation in an organized and aesthetically pleasing
> way.
>
>  https://makruger.github.io/website/pages/docs/handbook.html does not
> work.  https is broken in your css.
>
> I agree a bit on this.  I do not like Confluence, but it does make for
> a nice looking index layout.  I am really a fan of mediawiki and I do
> not understand why they chose to go with the Atlassian Confluence
> Community License when mediawiki is FOSS.  To each there own and I am
> sure it was thought about.
>
> I like straightforward layouts that do not obfuscate things.  I want
> all the information on one pagenot a million different menus.  One
> large TOC/index and all the text at my fingertips.  i should not need
> a search engine to search a manual.  If I open up a handbook, I want
> the handbook.
>
> Though, if what you have created were to be accepted, you are adding
> more work.  I do not OI has a dev lead or team right now right?  Who
> is going to support it?  The support/work might not be in vain though
> because documentation should support the release.  It is very
> frustrating for users to use an OS and not find the docs they need.
> Or find out dated docs.  Do you think a developer would take time to
> fix docs though when they already have man pages and README's?
>

I would actually be more confortable editing source files and doing PRs.
In a math/physics research environment everything is written in LaTeX (also
mark-up language for  algo/code-related documents).
Even applications for fundings are shared in git and merged from different
branches.


> If you were to link the docs via github to code changes, every release
> could have its handbook frozen in time/git releases/names for each
> release.  In fact I think this could be a powerful feature if OI ever
> does an LTS release.
>

I think so too.


>
> ___
> oi-dev mailing list
> oi-dev@openindiana.org
> http://openindiana.org/mailman/listinfo/oi-dev
>



-- 
---
Praise the Caffeine embeddings
___
oi-dev mailing list
oi-dev@openindiana.org
http://openindiana.org/mailman/listinfo/oi-dev

Re: [oi-dev] demonstration docs website

2016-05-06 Thread WebDawg 
> Date: Sun, 1 May 2016 00:30:55 -0400
> From: Michael Kruger 
> To: OpenIndiana Developer mailing list ,
> Discussion list for OpenIndiana 
> Subject: [oi-dev] demonstration docs website
> Message-ID: <5725867f.9030...@gmail.com>
> Content-Type: text/plain; charset=utf-8; format=flowed
>
> Hello all,
>
> Here is a little something I have been working to help showcase
> documentation for the OpenIndiana project.
>
> Currently hosted are:
>
> OpenIndiana FAQ (Complete, but still growing and improving)
> OpenIndiana Handbook (little more than a template at this point)
> OpenSolaris Books (41 titles from the 2009 redistributable docs release)
>
> All of this resides on github, so further evolution of this website and
> it's content simply follows existing development practices.
>
> Here is the URL: http://makruger.github.io/website/
>
> Enjoy,
>
> Michael
>

I am starting from the first email because there have been so many
replies and responses to this one and no one has provided anything but
it seems negative feedback to this git site.  I also see very little
contribution to the subject of documentation.

Right now a majority of OpenIndiana docs are on the wiki here:
http://wiki.openindiana.org/oi/OpenIndiana+Wiki+Home

I have never even heard of http://dlc.openindiana.org/docs/ until it
was mentioned a few days ago.

I like wiki's.  Personally I use archlinux and they have one of the
best wiki's I have ever used.  I like wikis because they are so
dynamic.  It is easy for me to edit, easy for me to fix.

1) Place documentation under distributed version control.

Not all documentation I think should be under version control.
Though, documentation created by the people that help create OI I
think would.  I really think that what you are creating is not a
documentation site but a new handbook.  Is there a public, updatable,
handbook right now?

I would keep the wiki AND have this nice handbook.  I really think the
front facing page should be integrated somewhere branching off of the
main site to summarize the entirety of the OI documentation structure.

It seems like, with the wiki and handbook approach, you would be
duplicating work but then lets take a look at this page:

http://wiki.openindiana.org/pages/viewpage.action?pageId=4883847

That page needs updated, it looks like 4k problem has been fixed, or
possibly not.  Why are people commenting instead of fixing the wiki
itself?

If you have a handbook that developers can edit simply and quickly
once a problem has been fixed in OI, is this not better?  Or is this a
problem solved by man pages?

2) Lower the bar of entry to the documentation process.
I do not know why the bar is high right now?  Can you explain this
more?  Making an account on the wiki is not hard.
Making an account on git is not hard either but I would like to
mention that most people are used to editing wikis.

3) Make changes and quickly deploy those changes in some kind of
automated fashion (e.g. continuous integration).
Once again, I already talked about developer -> git docs editing, but
can you please explain this more?  Wikis are just click and edit.

4) Present the documentation in an organized and aesthetically pleasing way.

 https://makruger.github.io/website/pages/docs/handbook.html does not
work.  https is broken in your css.

I agree a bit on this.  I do not like Confluence, but it does make for
a nice looking index layout.  I am really a fan of mediawiki and I do
not understand why they chose to go with the Atlassian Confluence
Community License when mediawiki is FOSS.  To each there own and I am
sure it was thought about.

I like straightforward layouts that do not obfuscate things.  I want
all the information on one pagenot a million different menus.  One
large TOC/index and all the text at my fingertips.  i should not need
a search engine to search a manual.  If I open up a handbook, I want
the handbook.

Though, if what you have created were to be accepted, you are adding
more work.  I do not OI has a dev lead or team right now right?  Who
is going to support it?  The support/work might not be in vain though
because documentation should support the release.  It is very
frustrating for users to use an OS and not find the docs they need.
Or find out dated docs.  Do you think a developer would take time to
fix docs though when they already have man pages and README's?

If you were to link the docs via github to code changes, every release
could have its handbook frozen in time/git releases/names for each
release.  In fact I think this could be a powerful feature if OI ever
does an LTS release.

___
oi-dev mailing list
oi-dev@openindiana.org
http://openindiana.org/mailman/listinfo/oi-dev

Re: [oi-dev] demonstration docs website

2016-05-04 Thread Michael Kruger 

On 05/04/2016 06:52 AM, Alexander Pyhalov wrote:

> Hi, Michael.
>
> Thank you for your work.
> To move further I think we should consider several questions...
>
> 1) Someone should look through the docs... So , reviewers are welcome.
> Have you changed "OpenSolaris Redistributable Books" in any way or just
> created the index and converted them to docbook? How do we mark parts of
> the books which are not currently actual? How are we going to update
> them (create new document or mark current document as reviewed)? How
> http://makruger.github.io/website/pages/docs/handbook.html and
> http://wiki.openindiana.org/oi/OpenIndiana+Handbook are related? What
> parts are missing?



The website is composed of 3 separate components:

1) The Awestruct web framework

And the contents of 2 GitHub repositories:

2) https://github.com/makruger/openindiana-docs
3) https://github.com/makruger/docs_20090715

The Awestruct framework works with an Asciidoctor plugin to compile 
Asciidoc text markup content pages into HTML5 and then deploys it to a 
gh-pages branch. This branch is published to GitHub pages.


The compiler parses through everything it finds and anything which is 
already compiled (or for which there is no parser) is simply copied over 
without any further processing. The main index as well as header/footer 
layouts, etc., are composed in HAML (but can also include snippets of HTML).


The 2 GitHub repositories are not configured as submodules, but going 
forward they probably should be, or alternately things could remain as 
they are and inclusive of it all.


The openindiana-docs repository consists of the FAQ I previously worked 
on as well as a skeleton for an updated handbook. It also includes 
several informal 'work products' containing notes and guidance for 
anyone working on the docs project. Some of these work products could be 
used in the creation of other documents, others are better reserved for 
reference use only.


As for the handbook, I never envisioned it becoming as comprehensive the 
OSOL books, but rather be used as a supplement to them. Call it a guide 
for new users wanting to quickly get up to speed with the operating system.


The docs_20090715 repository contains the redistributable books. Here I 
simply extracted the zipfile (which already contained compiled HTML 
along with the raw XML sources) and wrote several index pages which 
linked it all together.


These books are as originally released without any further editing. I do 
not yet have a formal process for updating the books. Up until this 
point my only concern has been to host them as they are and develop a 
process for updating them at a later date.




> 2) What is the process of contribution, how site is generated? What
> tools are used to work on the docs ( asciidoctor + git ?)?



At this time the site is manually generated. Though in the future it 
could be automated using Travis-CI.


For those interested in helping with the development of the website 
itself, Awestruct can be run locally in development mode. This requires 
a Ruby environment, although this can be simplified in the future by 
using Gradle.


For those who wish to contribute to new or existing content, all that is 
required is a text editor. I use VIM along with an asciidoc VIM plugin. 
There is also an Asciidoctor IDE by the name of AsciidocFX. The IDE uses 
an Atom like text editor along with a live preview of the parsed text.


For those who wish to use VIM, there is an Asciidoctor plugin available 
for firefox (and Chrome as well) which can be used to parse the document 
and provide a close approximation of it's final rendered form.


Content is written using Asciidoc text markup (or more specifically the 
enhanced Asciidoctor version of it).


In either use case (content creation or website development), 
contributors would fork the repository and submit a pull request to have 
their changes incorporated. Someone (most likely me or anyone else who 
wishes to help) would review and merge the changes.


As for linking new documents with site menus, this is a manual process, 
but could be simplified by using TOC pages and adding and simply adding 
a new line item for the additional document.




> 3) How do you propose to incorporate documentation site in current OI
> web site? How do you suggest to consider what articles should live on
> the wiki, which - on documentation site? How these two sites are going
> to be related?



These are very good questions. I think initially we can provide a menu 
option on word press to redirect users to the docs site. Other pages may 
contain references residing on the docs site much as we do today with 
the Wiki.


As for deciding what goes where, unfortunately I do not yet have an 
answer. My inspiration for this project has been the Jenkins project who 
as far as I know have retained their Wiki. We could probably look to 
them for an answer to this question.


Michael

Re: [oi-dev] demonstration docs website

2016-05-04 Thread Alexander Pyhalov 

On 05/01/2016 07:30, Michael Kruger wrote:

Hello all,

Here is a little something I have been working to help showcase
documentation for the OpenIndiana project.

Currently hosted are:

OpenIndiana FAQ (Complete, but still growing and improving)
OpenIndiana Handbook (little more than a template at this point)
OpenSolaris Books (41 titles from the 2009 redistributable docs release)



Hi, Michael.

Thank you for your work.
To move further I think we should consider several questions...

1) Someone should look through the docs... So , reviewers are welcome. 
Have you changed "OpenSolaris Redistributable Books" in any way or just 
created the index and converted them to docbook? How do we mark parts of 
the books which are not currently actual? How are we going to update 
them (create new document or mark current document as reviewed)? How 
http://makruger.github.io/website/pages/docs/handbook.html and 
http://wiki.openindiana.org/oi/OpenIndiana+Handbook are related? What 
parts are missing?


2) What is the process of contribution, how site is generated? What 
tools are used to work on the docs ( asciidoctor + git ?)?


3) How do you propose to incorporate documentation site in current OI 
web site? How do you suggest to consider what articles should live on 
the wiki, which - on documentation site? How these two sites are going 
to be related?


--
Best regards,
Alexander Pyhalov,
system administrator of Southern Federal University IT department

___
oi-dev mailing list
oi-dev@openindiana.org
http://openindiana.org/mailman/listinfo/oi-dev

Re: [oi-dev] demonstration docs website

2016-05-02 Thread Nikola M 

On 05/ 2/16 06:29 PM, WebDawg wrote:
You guys are all so very confusing.  It seems to me someone put 
together an example docs site and everyone keeps talking about how it 
is hosted on github, licensing, and stuff.


Please hit "reply" when posting to the list so your answers stay in-line 
on the list and are not top-posted.


Did I miss something or did the individual that submitted it say it 
has to stay there?


I get the XML thing...it seems like that is one of the big real issues 
that it does not conform to an existing OI standard.


There is no official standard, there are docs in XML and can be renewed.

I mean, the individual does not have to use your servers to develop 
something...


Sure, but individual wants to decide what is in OI's docs and is not and 
that is OI"s issue not only individuals.


And it is argued that it is best for docs renewal and additions to stay 
within OI's site so they could be under OI project and that it needs to 
follow licensing, contributing agreement etc. and that rewriting it from 
the start is painful workaround when there's existing docs.


Also there is a Wiki to write short articles instead of external sites. 
(wiki.openindiana.org)




Does the content suck?  Is it good?  Everyone is now talking about 
changing documentation standards?


You can look for yourself :)
It surely misses all those Opensolaris books listed on 
dlc.openindiana.org/docs



___
oi-dev mailing list
oi-dev@openindiana.org
http://openindiana.org/mailman/listinfo/oi-dev

Re: [oi-dev] demonstration docs website

2016-05-02 Thread WebDawg 
You guys are all so very confusing.  It seems to me someone put together an
example docs site and everyone keeps talking about how it is hosted on
github, licensing, and stuff.

Did I miss something or did the individual that submitted it say it has to
stay there?

I get the XML thing...it seems like that is one of the big real issues that
it does not conform to an existing OI standard.

I mean, the individual does not have to use your servers to develop
something...

Does the content suck?  Is it good?  Everyone is now talking about changing
documentation standards?
___
oi-dev mailing list
oi-dev@openindiana.org
http://openindiana.org/mailman/listinfo/oi-dev

Re: [oi-dev] demonstration docs website

2016-05-02 Thread Nikola M 

On 05/ 2/16 03:44 PM, Bob Friesenhahn wrote:

On Mon, 2 May 2016, Nikola M wrote:


On 05/ 2/16 08:56 AM, Alan Coopersmith wrote:

On 05/ 1/16 10:48 PM, Nikola M wrote:
*You aether accept open documentation license including Contributor 
agreement to

OI or you contribute your time at somewhere else.*


Why don't you let the people who run the project decide whether or 
not to accept

contributions before you chase everyone away?


There is no one who "runs the project" except us all, here and now, 
together.

Everyone is free to contribute in all possible ways he seems fit.

Support proprietary projects is not very high on my list.


You made a lot of good points but in total it felt hostile.  It seems 
like you are saying that if perfection is not possible, then the work 
is not worth doing.




Like I haven't said so ;) Having good intentions in mind can help not 
avoiding the topic itself.


It seems most important that the license for the documentation 
(regardless of where it is initially developed) is suitable for other 
uses in OpenIndiana and that it can be incorporated in OpenIndiana 
documentation (or cut/pasted as part of blogs) as maintainers/athors 
see fit.


You are right.
And since we can't change existing Opensolaris documentation licence 
that needs to renewed.. we ar kind of married to it unless we want to 
loose all docs.
I don't think starting from scratch is meaningful and neither having 
then outside openindiana site.


I suggest that Wiki (wiki.openindiana.org) is a nice place to write 
shorter articles that can be easily reviewed and changed in wiki way and 
as a plus, they are instantly available on OI's site.

(and after, wiki be incorporated into documentation).

Actually, changes to docs need time and starting to review illumos 
changes and later OI's changes since Opensolaris, so we can have them 
all covered and start implementing changed on day to day bases at a moment.
Since there are so many docs available, 
(http://dlc.openindiana.org/docs/) it is wise renewing them.



___
oi-dev mailing list
oi-dev@openindiana.org
http://openindiana.org/mailman/listinfo/oi-dev

Re: [oi-dev] demonstration docs website

2016-05-02 Thread Bob Friesenhahn 

On Mon, 2 May 2016, Nikola M wrote:


On 05/ 2/16 08:56 AM, Alan Coopersmith wrote:

On 05/ 1/16 10:48 PM, Nikola M wrote:
*You aether accept open documentation license including Contributor 
agreement to

OI or you contribute your time at somewhere else.*


Why don't you let the people who run the project decide whether or not to 
accept

contributions before you chase everyone away?


There is no one who "runs the project" except us all, here and now, together.
Everyone is free to contribute in all possible ways he seems fit.

Support proprietary projects is not very high on my list.


You made a lot of good points but in total it felt hostile.  It seems 
like you are saying that if perfection is not possible, then the work 
is not worth doing.


It seems most important that the license for the documentation 
(regardless of where it is initially developed) is suitable for other 
uses in OpenIndiana and that it can be incorporated in OpenIndiana 
documentation (or cut/pasted as part of blogs) as maintainers/athors 
see fit.


Bob
--
Bob Friesenhahn
bfrie...@simple.dallas.tx.us, http://www.simplesystems.org/users/bfriesen/
GraphicsMagick Maintainer,http://www.GraphicsMagick.org/

___
oi-dev mailing list
oi-dev@openindiana.org
http://openindiana.org/mailman/listinfo/oi-dev

Re: [oi-dev] demonstration docs website

2016-05-02 Thread Nikola M 

On 05/ 2/16 10:30 AM, Илья Архипкин wrote:
Very well written, and you officially their conviction simply am not 
who wrote a lot of paperwork, but in this segment of the Russian order 
to find a lot of people are erotic, free content. And to compete with 
my domain get a DDoS-attacks, spam attacks. Moreover, against the 
background of Russophobia


I think you are a bit offtopic :) ,
I am sorry your site has attacked.

You can maybe even use Russian when posting, if providing some automatic 
translation (was using proprietary service 
http://www.bing.com/translator for Ggerman in both ways), so maybe you 
can post in both Russian and English so your posts can be more 
understandable? :P



___
oi-dev mailing list
oi-dev@openindiana.org
http://openindiana.org/mailman/listinfo/oi-dev

Re: [oi-dev] demonstration docs website

2016-05-02 Thread Илья Архипкин 
Very well written, and you officially their conviction simply am not who 
wrote a lot of paperwork, but in this segment of the Russian order to 
find a lot of people are erotic, free content. And to compete with my 
domain get a DDoS-attacks, spam attacks. Moreover, against the 
background of Russophobia and events in the Donbass


Regards, Arhipkin Ilya


___
oi-dev mailing list
oi-dev@openindiana.org
http://openindiana.org/mailman/listinfo/oi-dev

Re: [oi-dev] demonstration docs website

2016-05-02 Thread Nikola M 

On 05/ 2/16 08:56 AM, Alan Coopersmith wrote:

On 05/ 1/16 10:48 PM, Nikola M wrote:
*You aether accept open documentation license including Contributor 
agreement to

OI or you contribute your time at somewhere else.*


Why don't you let the people who run the project decide whether or not 
to accept

contributions before you chase everyone away?


There is no one who "runs the project" except us all, here and now, 
together.

Everyone is free to contribute in all possible ways he seems fit.

Support proprietary projects is not very high on my list.


___
oi-dev mailing list
oi-dev@openindiana.org
http://openindiana.org/mailman/listinfo/oi-dev

Re: [oi-dev] demonstration docs website

2016-05-02 Thread Nikola M 

On 05/ 1/16 03:13 PM, Michael Kruger wrote:
point, the site and it's contents automatically builds and deploys 
upon git commit.
Building prior making something should be done on OI's servers to ensure 
it includes only what is in the source.



All Openindiana infrastructure things can be easily covered within OI's
infrastructure, regarding the need for test sites, GIT repositories, and
in-development documentation hosting.

I disagree.


All infrastructure needs are easily covered with OI's infrastructure and 
there is nothing to agree nor disagree upon, that is just a fact. 
Spinning up the git is easily done.
Example: trying to share release ISO or docs archive and one quickly 
finds out needing site and address.


Someone needs to review it and stay behind it's quality, so that people 
can be sure it's all good for them.
Reviewing process is for that, so in a sense of community effort you 
can't be "your own boss" and more important "on your own site". There is 
already site and it is openindiana.org. One place to look for a project 
not a 'quadrillion' different ones, when talking about ease of 
contribution and project existance.




A project is not defined by where it hosts it's code, docs, etc.


Sure documentation is what defines a distribution. If it is not on OI's 
servers, there is no OI, but number of not connected efforts, 
distributed across internet and that is not what the project is.


OI can't depend on someone's personal wits wither he/she should one day 
delete external contents or manage it or should it be available under 
OI's documentation license.


Questions of documentation are deeply representing software distribution 
itself and as I see this this represent non coordination and not reusing 
existing docs and is pulling in wrong direction.


If one spends enough time doing something alone, then it becomes non 
maintainable.
Same thing is with making processes better. One can always spend 3 years 
in basement doing something in separate way, but it's not needed.




Besides, why re-invent the wheel?


Exactly. Just use Opensolaris docs and see if you can improve on them. 
Do it publicly and loudly so you are not alone at any moment working on 
them.
There is already a process in transforming them and if it is needed to 
be refreshed it's ok.


Writing new articles all over again, just to be "different licensed" 
does not sounds like a effort good spent.


There is Openindiana  Wiki for brand new (possibly awesome) articles.
wiki.openindiana.org

Github is out there and many projects (much larger than OI) are using 
it to their full advantage. For an example, go have a look at the 
Jenkins project.


Depending on any external site - is a phase for many small projects: OI 
is not intending to being a small project.
We generally don't need Github for documentation, when we have our own 
servers. Why using something less good in a sense of project existence, 
and leave it to external entity to depend upon?



All contributions to OI's docs must follow it's license and can't be
re-licensed (Marguger asked weither he can re-license Opensolaris docs
to some other docs, answer is:no.


Licensing is something which should be discussed further. 


No it can't be discussed, since there is a mountain of Opensolaris 
documentation already licensed and it must be followed to be extended. 
It is what is required to follow in order to help OI's documentation.

http://dlc.openindiana.org/docs/
http://dlc.openindiana.org/docs/2009.06/pdl_version_101.pdf

In particular we should talk about what we need to do to ensure we're 
in compliance with whatever license applies to each work.


We don't need wasting time in applying license on each work.
There is contributor agreement that covers contribution to Openindiana 
project, the same as Sun did and it allows re-using any contributed work.
it's simple, it's efficient, easy to understand why it needs to exist 
(so project can use it as pleased and not bragging about every single 
contribution mention)  and surely any non-derived work author can re-use 
it too, no matter what agreement he/she signed, If that answers tour 
question of re-licensing your work.




That said I am not convinced the PDL should be applied to new works 
that do not contain any previously PDL licensed content. New works 
could for example use an MIT license.


New work is interesting area. It comes from conclusion that nothing else 
exists
(it surely does, http://dlc.openindiana.org/docs/2009.06/ , 
http://wiki.openindiana.org)

and that the author is smartest person in the world to do something new.

It is surely good to try something new, but to have Openindiana name on 
it, it must
- go through review process , - include existing docs and - be hosted on 
openindiana.org.




A copy of the PDL license is hosted along with the books here: 
http://makruger.github.io/website/pages/books/pdl.html


This is not OI official location and will never be... Please don't paste

Re: [oi-dev] demonstration docs website

2016-05-02 Thread Alan Coopersmith 

On 05/ 1/16 10:48 PM, Nikola M wrote:

*You aether accept open documentation license including Contributor agreement to
OI or you contribute your time at somewhere else.*


Why don't you let the people who run the project decide whether or not to accept
contributions before you chase everyone away?

-alan-

___
oi-dev mailing list
oi-dev@openindiana.org
http://openindiana.org/mailman/listinfo/oi-dev

Re: [oi-dev] demonstration docs website

2016-05-02 Thread Aurélien Larcher 
On Mon, May 2, 2016 at 7:48 AM, Nikola M  wrote:

> On 05/ 1/16 04:45 PM, Aurélien Larcher wrote:
>
>
>  I would like you have been doing this not alone, but within Openindiana
>> community and cooperation with others, with announcing it here.
>>
>
> Oh but this has been the opportunity of several discussion on irc and by
> email.
> I think the idea of a proof of concept before involving more people is not
> a problem per se.
>
>
> Involving more people in a process that results in something with lower
> quality then we currently have , while not accepting OI's documentation
> licensing does not qualify as OI's project.
>
>
> In any case, the initial questions were:
> - review existing documentation systems from BSD and Linux distributions
> - come up with a process lowering the barrier for contributions
> - allow conversion between different formats
> - minimize the "man/hour" cost of deployment and need for maintenance
>
> IMHO Michael's solution satisfies all the requirements.
> When/If/As soon as the proposed solution is considered technically, the
> considerations that you raise (like migration to OI infrastructure) should
> be addressed in a next stage but are orthogonal to current proposal.
>
>
> Next stage is almost always never.
> If documentation is not on OI's infrastructure it is not OI's
> documentation.
> If it does not use Oi's documentation licensing, it's not OI
> documentation.
> If it is not contributed with contribution agreement , it is not OI
> documentation.
> If it is done without review and some plan of priorities, it's not OI's
> documentation.
>
> - We are not BSD nor Linux and looking at them could help in some extent
> in the future, but we have illumos and Opensolaris documentation to
> maintain and extend, not to re-invent new wheels here.
> - Lowering the involvement process should include people in the community,
> and not supporting effort that goes against OI's documentation principles.
> It also does not includes re-inventing the wheels.
> (Reinventing the whell includes rewriting already existing docs, instead
> of renewing existing one.)
> - Communication between formats it already done with XML and exporting to
> html and PDF
>
> What we see here is Wiki reinvented and OI already has a Wiki!
> Please use Wiki if you think you have some great article to write and you
> want it to be part of Openindiana. Sites like .ninja and github web pages
> are not places for Openindiana docs, especially if they are not licensed to
> be OI docs.
> - Minimizing man/hour requires accepting OI's documentation licenses and
> there is no compromise about that.
> *You aether accept open documentation license including Contributor
> agreement to OI or you contribute your time at somewhere else.*
>

I am not going to waste my time again.


>
>
> ___
> oi-dev mailing list
> oi-dev@openindiana.org
> http://openindiana.org/mailman/listinfo/oi-dev
>



-- 
---
Praise the Caffeine embeddings
___
oi-dev mailing list
oi-dev@openindiana.org
http://openindiana.org/mailman/listinfo/oi-dev

Re: [oi-dev] demonstration docs website

2016-05-01 Thread Aurélien Larcher 
Hello !
That looks very promising !




> I would like you have been doing this not alone, but within Openindiana
> community and cooperation with others, with announcing it here.
>

Oh but this has been the opportunity of several discussion on irc and by
email.
I think the idea of a proof of concept before involving more people is not
a problem per se.


>
> So this should be hosted on openindiana.org.
> and "© The OpenIndiana Project 2016 - All Rights Reserved" is invalid and
> is not valid open documentation license, even someone could argue it
> actually represent accepting contributor agreement, but I suggest to also
> use standard documentation license so it could be reused like Opensolaris
> docs can be used because of that.
> There is also reason why Opensolaris docs are made in XML using XML
> editing applications, so we can easily have html and PDF versions of any
> docs, using existing tools.
>
> You should check and consult with someone before moving with this. Doing
> it alone is never good as it doesn't represent OI as a community product
> and more heads are always smarted then one. :)
>

Initiatives should be welcome and then how the community can embrace them
is another question.

In any case, the initial questions were:
- review existing documentation systems from BSD and Linux distributions
- come up with a process lowering the barrier for contributions
- allow conversion between different formats
- minimize the "man/hour" cost of deployment and need for maintenance

IMHO Michael's solution satisfies all the requirements.
When/If/As soon as the proposed solution is considered technically, the
considerations that you raise (like migration to OI infrastructure) should
be addressed in a next stage but are orthogonal to current proposal.
___
oi-dev mailing list
oi-dev@openindiana.org
http://openindiana.org/mailman/listinfo/oi-dev

Re: [oi-dev] demonstration docs website

2016-05-01 Thread Michael Kruger 

On 05/01/2016 04:56 AM, Nikola M wrote:


I would like you have been doing this not alone, but within Openindiana
community and cooperation with others, with announcing it here.

Also using Openindiana brand name outside openindiana.org for site names
(like .ninja etc) is not good, since it is where search engines might
forward people and that lowers openindiana.org rank.



I agree.

Should this technology demonstration be accepted, the site should adopt 
an OpenIndiana.org cname. We could for example call it 
docs.openindiana.org. And naturally it would also follow to move to 
repository itself under OpenIndiana project's github umbrella.


Being a technology demonstration, the announcement of this site is 
primarily to showcase what is possible with today's front end web 
development technologies.


For example, the site is completely static, and uses a responsive and 
mobile friendly CSS layout. There are no page generating engines, nor 
any databases, just a GitHub repository with a publishing branch hosted 
on GitHub pages.


Not only that, but the repository can be configured for continuous 
integration with Travis-CI. At that point, the site and it's contents 
automatically builds and deploys upon git commit.





All Openindiana infrastructure things can be easily covered within OI's
infrastructure, regarding the need for test sites, GIT repositories, and
in-development documentation hosting.



I disagree.

A project is not defined by where it hosts it's code, docs, etc.

Besides, why re-invent the wheel?

Github is out there and many projects (much larger than OI) are using it 
to their full advantage. For an example, go have a look at the Jenkins 
project.





All contributions to OI's docs must follow it's license and can't be
re-licensed (Marguger asked weither he can re-license Opensolaris docs
to some other docs, answer is:no.




Licensing is something which should be discussed further. In particular 
we should talk about what we need to do to ensure we're in compliance 
with whatever license applies to each work.


That said I am not convinced the PDL should be applied to new works that 
do not contain any previously PDL licensed content. New works could for 
example use an MIT license.


A copy of the PDL license is hosted along with the books here: 
http://makruger.github.io/website/pages/books/pdl.html





That includes contributor agreement, now to OI, so that documentation
dos not need nor should include any personal "Copyright" notices, except
CVS logs and contributor notes.
So this should be hosted on openindiana.org.
and "© The OpenIndiana Project 2016 - All Rights Reserved" is invalid
and is not valid open documentation license, even someone could argue it
actually represent accepting contributor agreement, but I suggest to
also use standard documentation license so it could be reused like
Opensolaris docs can be used because of that.




I disagree.

The PDL contributor agreement provides full copyright assignment with 
"all rights reserved" to both the original document author(s) as well as 
to anyone making changes.


The spirit of the contributer agreement is to keep track of who made the 
changes, so they can be given proper credit.


Git fully meets the requirements of PDL section 3.3, as each commit 
shows the author, contact email, and what was changed.





There is also reason why Opensolaris docs are made in XML using XML
editing applications, so we can easily have html and PDF versions of any
docs, using existing tools.




I disagree.

There is absolutely no good reason to use XML in the production of new 
documentation. Nor is there any good reason for existing docs to even 
remain in the XML format (Here I am referring to the OSOL books).


The text markup technologies used in this demonstration site (asciidoc 
along with the asciidoctor documentation framework) can easily produce 
HTML and PDF. They can also produce EPUB, docbook, man pages, and a 
bunch of other formats as well.


For more information (and a convincing argument against the use of text 
editors, XML, etc.) I would refer you to the Asciidoctor website:


http://asciidoctor.org/docs/what-is-asciidoc/




You should check and consult with someone before moving with this. Doing
it alone is never good as it doesn't represent OI as a community product
and more heads are always smarted then one. :)
If doing alone after it grows, it gets harder to fix issues and then you
used to complain that there are too many issues and changes with your
texts. That is normal to have issues :)



Yes of course, the community should be involved with the evolution of 
the project's documentation and the technologies used to present them.


Working on this website or any of content is as simple as forking the 
repository and submitting a pull request.



Michael

___
oi-dev mailing list
oi-dev@openindiana.org
http://openindiana.org/mailman/listinfo/oi-dev

Re: [oi-dev] demonstration docs website

2016-05-01 Thread Nikola M 

On 05/ 1/16 06:30 AM, Michael Kruger wrote:

Hello all,

Here is a little something I have been working to help showcase 
documentation for the OpenIndiana project.


Currently hosted are:

OpenIndiana FAQ (Complete, but still growing and improving)
OpenIndiana Handbook (little more than a template at this point)
OpenSolaris Books (41 titles from the 2009 redistributable docs release)

All of this resides on github, so further evolution of this website 
and it's content simply follows existing development practices.


Here is the URL: http://makruger.github.io/website/


I would like you have been doing this not alone, but within Openindiana 
community and cooperation with others, with announcing it here.


Also using Openindiana brand name outside openindiana.org for site names 
(like .ninja etc) is not good, since it is where search engines might 
forward people and that lowers openindiana.org rank.


All Openindiana infrastructure things can be easily covered within OI's 
infrastructure, regarding the need for test sites, GIT repositories, and 
in-development documentation hosting.


All contributions to OI's docs must follow it's license and can't be 
re-licensed (Marguger asked weither he can re-license Opensolaris docs 
to some other docs, answer is:no.
That includes contributor agreement, now to OI, so that documentation 
dos not need nor should include any personal "Copyright" notices, except 
CVS logs and contributor notes.


So this should be hosted on openindiana.org.
and "© The OpenIndiana Project 2016 - All Rights Reserved" is invalid 
and is not valid open documentation license, even someone could argue it 
actually represent accepting contributor agreement, but I suggest to 
also use standard documentation license so it could be reused like 
Opensolaris docs can be used because of that.
There is also reason why Opensolaris docs are made in XML using XML 
editing applications, so we can easily have html and PDF versions of any 
docs, using existing tools.


You should check and consult with someone before moving with this. Doing 
it alone is never good as it doesn't represent OI as a community product 
and more heads are always smarted then one. :)
If doing alone after it grows, it gets harder to fix issues and then you 
used to complain that there are too many issues and changes with your 
texts. That is normal to have issues :)



___
oi-dev mailing list
oi-dev@openindiana.org
http://openindiana.org/mailman/listinfo/oi-dev