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

[Adam Števko]

Hello folks,

After severals months of Michael’s hard work, we are glad to present a future basis for new OpenIndiana documentation. The documentation can be found at http://docs.openindiana.org. 

Michael tried to make the contribution barrier as low as possible, so here are couple of things:

    • Documentation fixes/additions/removals all leverage the Github pull request (PR) system.
    • Every PR is automatically built and the result of each build is marked in the PR menu. With this, you will know in a matter of minutes whether the change you made is mergeable and satisfies our checks.
    • After a PR is merged, the change is automatically built and deployed to http://docs.openindiana.org

To begin contributing, the process is described in great detail at http://docs.openindiana.org/contrib/getting-started/. Contributing directly from OI is fully supported (either follow steps in the guide or "pkg install mkdocs"). You may also contribute from non-OI operating systems. 

With this pipeline, we can achieve fast and automated deployments and people can contribute with confidence.  Therefore, I would like to invite _ALL_ people that are somehow related to OpenIndiana, most notably _USERS_ to participate in the contributions. 

Here are some of the ways you may contribute:

    • Proofreading the documentation. The more times the documentation is read, the better and more precise it will be. Having more eyes on the content will boost our chance to spot errors and outdated content. As the ranks of OI developers are steadily growing and new features/changes are being incorporated faster than ever, the documentation will quickly become out of date. With more people contributing to the documentation effort, this problem can be prevented.

    • Review contributed content. There is never enough reviewers for the content. So, any PR with content addition/modification/removal can use your review.

    • Write new content and add new section. The more content we can get, the better the documentation will be.

    • Adopt certain sections and actively maintain them as more new features are being delivered to OpenIndiana.

I would also like to warn people that you still have to consider this project as work in progress and it does not serve as Wiki replacement. The longterm plan of this project is to serve as the end user documentation and fulfill a role within the OI community much as the FreeBSD handbook does for the FreeBSD community. Those who have used the FreeBSD handbook will know what I’m talking about. 

The OpenIndiana wiki has a lot of content, but a huge amount of it is outdated and not relevant any more. However, this will be solved in the future by doing another call for participants. Notes related to the OpenIndiana development are to stay on our wiki in the future.

I hope the majority of you will like this project and we will see new contributions flowing in!

P.S: In the future, we also plan to deliver an offline copy of this documentation included with the installation medias. More information will be provided later.

Cheers,
Adam