Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create documentation for the Eclipse OMR project - Contributions welcome! #165

Open
dorrab opened this issue Jul 22, 2016 · 6 comments

Comments

Projects
None yet
5 participants
@dorrab
Copy link

commented Jul 22, 2016

Eclipse OMR is in need of better documentation and we welcome your help.

Please use this Issue to:

  • discuss documentation related topics
  • identify any missing documentation.

You are more than welcome to contribute directly by sending pull requests (PR) or let us know about any sections that you feel are poorly documented and need to improve.

Thank you

@charliegracie

This comment has been minimized.

Copy link
Contributor

commented Aug 3, 2016

@dorrab is there a starting point for the website? It will be easier to contribute text/documentation once there is a starting point up and running.

@dorrab

This comment has been minimized.

Copy link
Author

commented Aug 3, 2016

Yes, a website using Jekyll is ready.
We have a few outstanding questions to resolve before contributing the code. One of them from
@mstoodle. He asked if the website should be contributed to the master branch under a "docs" directory ? Or would it be better to have it in a separate branch like "gh-pages" ?
Any thoughts?

@ktbriggs

This comment has been minimized.

Copy link
Contributor

commented Sep 1, 2016

Do we have a common store or repo where prospective web structure and content can be checked in to be reviewed and tracked? For example - I have a blog post on DropBox, where I posted it for review and where it is accessible only to IBMers AFAIK. If it were on github reviewers could contribute feedback and track changes inline with current workflows. I think github submodule is a natural choice for storing and tracking documentation. Instead of a separate branch, it might be worth considering packaging the web site and other documentation artifacts as a git submodule.

Some thought should be given to separating blogs and articles (which can stand alone and be published independently of the website) and the structural elements of the web site. Also, we should have some guidance as to appropriate format and content of API-level documentation -- like templates for documenting components and public classes and methods.

@Krovatkin

This comment has been minimized.

Copy link
Contributor

commented Oct 4, 2016

@mstoodle , @vijaysun-omr , I'm putting together a small write-up on Inliner. It's not much at this point, but I was wondering if I could open a PR and keep building on it or would you prefer to see only the final product?

@mstoodle

This comment has been minimized.

Copy link
Contributor

commented Oct 5, 2016

Hi @Krovatkin,good to hear from you! So long as the write-up matches the current state of the inliner, which I believe has changed somewhat since your last direct exposure :) , we would certainly welcome it! I would suggest writing up a skeleton, sharing that for review, and then filling in the pieces at whatever pace you can manage. How does that sound?

Thanks for reaching out, Nick!

@mstoodle

This comment has been minimized.

Copy link
Contributor

commented Nov 26, 2016

@ktbriggs Sorry nobody responded to your question. The current web site is in a separate repository at https://github.com/eclipse/omr.website . The plan is for design documentation to live in the eclipse/omr repository alongside the code, and we'll set up some way to view that documentation if that's all you want to see. We'll get some links in the web site to point at the documentation here.

The web site is still a bit rough with lots of "content to be added later" sections, but it's now online at https://www.eclipse.org/omr .

So far, our blog articles are being published at DeveloperWorksOpen at https://developer.ibm.com/open/omr/ . There is a link to that site from our web site page (at the bottom left of the main page)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.