[oi-dev] demonstration docs website

Sun May 1 13:13:43 UTC 2016

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