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

Getting-started documentation needed #148

Closed
GoogleCodeExporter opened this issue Mar 16, 2015 · 2 comments
Closed

Getting-started documentation needed #148

GoogleCodeExporter opened this issue Mar 16, 2015 · 2 comments

Comments

@GoogleCodeExporter
Copy link

What steps will reproduce the problem?
1. Follow the existing build instructions.
2. Ask yourself (as a new user of Ontopia) "what now?"

What is the expected output? What do you see instead?

Ideally, I'd see a README file somewhere in the
ontopia-read-only/ or the ontopia-read-only/ontopia directory,
describing how to run the software, how to find its user
interface(s), and where to locate the user and developer
documentation.  (The document
ontopia-read-only/ontopia/doc/ontopia/overview.xml.html may be
what I'm looking for, or may not ... if I knew the answer, I
would no longer be looking for getting-started documentation
:).

What I see instead is no README or STARTUP or similar file.
The ontopia/doc directory has no obvious top-level document
to start from.  

In particular, it appears that the Web interface needs a
servlet environment of some kind.  Do I / should I / must I /
may I put Ontopia into my existing tomcat/webapps directory,
or ... ?

What I think is most needed is some way to ensure that someone
who checks everything out of subversion and runs the build can
do something (in particular, run some interesting software) to
make them feel that their investment in time has paid off.
Otherwise, we risk a user checking the project out, running
the build process, and running the tests, and coming to a dead
stop for some indefinite period.  (In my case, the dead stop
lasted about two months.)

This issue may overlap with issue 102.

Original issue reported on code.google.com by cms...@blackmesatech.com on 11 Nov 2009 at 11:22

@GoogleCodeExporter
Copy link
Author

I think this issue could be resolved by a README file saying roughly: 

    Once you build the current Ontopia distribution, and run the
    tests, you will probably want to play with the software.

    Everything you want will be inside the distribution you just
    built; the rest of the subversion checkout serves only to
    generate that distribution.  So (for example) don't bother
    looking at the documentation in $SVNROOT/ontopia/doc --
    instead, look at the documentation in
    $SVNROOT/build/dists/ontopia-N.N.N/doc.  

    If you're not already familiar with Ontopia, a good document
    to start with is the install.html in the doc directory of the
    build you're using.

    If you're just starting out, try starting the Tomcat server
    as described in section 4.3 of the install.html document,
    then in your Web browser navigate to http://localhost:8080/
    -- the web-based applications listed there will give you
    plenty to do.

Original comment by cms...@blackmesatech.com on 17 Nov 2009 at 6:38

@GoogleCodeExporter
Copy link
Author

That works! Added the README now. Thank you!

Original comment by lar...@gmail.com on 17 Nov 2009 at 7:26

  • Changed state: Verified
  • Added labels: Component-Documentation

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant