[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

Re: How to contribute to doc?



> On Jan 14, 2015, at 14:09, Shrinivasan T <tshrinivasan gmail com> wrote:
> 
> Team,
> 
> I saw the request for contributing to docs here.
> 
> https://blog.openshift.com/new-platform-new-docs-part/
> 
> interested in this.

Awesome! Thanks for helping out!

> 
> cloned the repo.
> 
> How can I start to write?

First off, you can see what the generated docs look like by going here:

https://ci.openshift.redhat.com/openshift-docs-master-testing/latest/welcome/index.html

This gets rebuilt with every merged commit to openshift-docs.

If you dig around, you will find that many of the topics are blank. But even the topics that aren't blank may benefit from additional content. Anything that you can do to improve the docs is extremely helpful.

Which gets me to your next question:

> Do I need to install the latest version on openshift and read all the code?

Install and run OpenShift? Yes. Read all the code? No.

Start by giving the sample application a try:

https://github.com/openshift/origin/tree/master/examples/sample-app

That will get you set up with a running OpenShift environment and a functioning application.

Once you've done that, consider, for instance, a docs page like Templates:

https://ci.openshift.redhat.com/openshift-docs-master-testing/latest/using_openshift/templates.html

Which lives here:

https://github.com/openshift/openshift-docs/blob/master/using_openshift/templates.adoc

You may not know what a template is, but here's a slide deck that I prepared for a talk in November:

http://reinvent-hripps.rhcloud.com/

This slide deck is pretty stale at this point, but there's a few slides on what templates are:

http://reinvent-hripps.rhcloud.com/#/48

And the sample app contains a few examples of how they are currently composed:

https://github.com/openshift/origin/blob/master/examples/sample-app/application-template-custombuild.json
https://github.com/openshift/origin/blob/master/examples/sample-app/application-template-dockerbuild.json
https://github.com/openshift/origin/blob/master/examples/sample-app/application-template-stibuild.json

The process of documenting OpenShift at this point is a lot like investigative journalism, but we've done some up front work to try and point people in the right direction, which gets me to your final question:

> 
> Shall we use the previous version doc as skleton for the structure?

The structure of the docs in the openshift-docs repo is not set in stone, but has been laid out in a way that makes sense as people discover, use, and eventually deploy their own OpenShift instance. So for now, for any brand new topics that you choose to add, you should try to find a logical topic group from the ones that already exist. And if you -do- need to create a new topic group, or want to add a new topic, make sure you add information about the new content to the _build_cfg.yml file per:

https://github.com/openshift/openshift-docs#document-set-metadata

Hopefully this answers your questions. Please feel free to reach out to us on IRC (FreeNode, #openshift-dev channel) if you are working on a docs PR and need some clarification on how something is meant to work.

Thanks again for expressing an interest in helping out with this!

--Harrison



[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]