[oi-dev] demonstration docs website

[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 
external links that draws attention from Openindiana project site, that 
is Openindiana.org.
Anything not hosted on openindiana.org is not to be considered by any 
means OI's.

Docs are also important for security, where changing docs can change how 
user's installations behave, including administration best practices and 
possible introduction backdoors through documentation/manuals.
That is why it's important to be "first party" and not "third party" in 
docs distribution, e.g. sharing links to external sites using 
Openindiana brand name is not the same as reading docs from OI's site.
That's why docs need to be controlled and managed and not dislocated 
across the web.

>> 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.

"all rights reserved" is not copyleft license. it is proprietary 
license. it is not in the spirit of Openindiana as an open and free 
software project to support proprietary licensed projects.
I am looking at that as a meaning to accept OI's contributor agreement 
but it seems that this wording of yours look forward to avoiding 
contributing to Openindiana.

Do you accept open source copyleft licensing as your contributing 
documentation license?
if not, I don't see why we have this conversation, if your project goal 
is to make "all rights reserved" type of result.
If you are thinking of making your own book, you are free to do so, 
without presenting as an Openindiana project.
Openindiana is not developing proprietary projects, but open ones, 
covered by various copyleft licenses that have open source.

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

The spirit of contributor agreement is to not needing to brag everywhere 
about who contributor is.
There is time and place for those and they are not in the docs 
themselves to distract people from reading it.
"Taking credit" is done by the act of contributing. If one accepts 
contributor's agreement, then Openindiana distribution can do with that 
work whatever it needs/wants and that is what contributor agreement is 
about.

You agree that your work be reused by an organization you are 
contributing to, without need nor power to stop it in the future.
That ensures organization can be free of litigation by authors and free 
form need to mention them all the time.
It is a way of defending projects from trolling with mentioning all 
people all the time without need.

People using OS distributions want to use them with their docs without 
hassle  and if someone really want to know who contributed, there are 
web pages, and version logs to point to and that's it.
(Like Help>About in desktop applications. One surely does not need every 
contributor's name beside every added option in an app)

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

Yeah, but there's difference if it's OI project or your private "all 
rights reserved" one.

>> 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. 

There is good reason to look at Opensolaris docs that are in XM:. to 
extend and improve existing documentation.  It is waste of time in 
rewriting it, it makes sense extending and improving it.

If one does not includes existing documentation in any improvement 
process, it is mostly waste of time, and especially if not accepting 
documentation licensing, I see it mainly as a way to avoid PDL docs 
licensing for some reason.

> Nor is there any good reason for existing docs to even remain in the 
> XML format (Here I am referring to the OSOL books).
There are already apps and process to convert them from XML to PDF books 
and Html, where PDF books look reasonably well, and can be easily 
printed, instead of putting just a bunch of text into PDF or something.

> The text markup technologies used in this demonstration site (asciidoc 
> along with the asciidoctor 

You never discussed it with anyone, send project proposal or announced 
you are working on something on this list as I remember.
We just see now you think you have finished project that intends to take 
documentation control outside Openindiana site and put it into your hands.

That is not going to happen at least without the fight for Openindiana 
distribution existence.
It is dissolving Openindiana in it's rebirth, making documentation 
proprietary licensed.

Maybe process can be re-used or your findings be looked at, but the way 
of you are doing it is not in coordination with people on Openindiana 
and this list.

if choosing accepting proprietary licensing for documentation I would 
choose to fully disregard it.
If there are technical merits, how come you don't except OI contributor 
agreement, docs licensing, hosting on OI site and you actually refuse to 
accept everything OI is and represent and force your own?

> 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:

This is also external service projects don't need to depend on to survive.
If tools for making something can't be available, then the product is 
not independent form third parties wits.
People surely need desktop application to edit documents on their 
machines, trying to replace that leavs people dependent on someone 
else's cloud and that it not what OI is.
With OI you can have your own infrastructure, servers and applications 
and it should include editing documents.

>
>> 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.

As proprietary licensed, this is not Openindiana documentation.

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

Be sure to require making git repository on OI's servers if you need a 
space to have a place for work on OI documentation.

Your proprietary licensed github page will not be the place for the 
Openindiana documentation development nor you are not allowed to veto 
the pulls and pushes to Openindiana documentation.

Don't confuse your work with actual Openindiana documentation, until you 
accept contributor agreement and documentation license.