JanusGraph / JanusGraph/janusgraph-foundationdb

Improve documentation

Open
#54 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Java
Stars
59
Forks
20
PR merge metrics
No merged PRs in 30d

Description

Hey guys. I've been trying to use Janusgraph with FDB and have so far been quite unsuccessful following the README.md. I feel there are quite a few areas that need to be better addressed in the documentation;

- `install.sh` will attempt to backup (`cp`) `janusgraph.sh` which only exists in the **full** versions of Janusgraph, and will therefor leave an error message. If the user should only be using the full version, then this should be explicit, otherwise an `if` statement might be more appropriate for this line.
- `install.sh` attempts to copy `lib/*` to `${JANUS_INSTALL_PATH}/ext`. This folder doesn't exist if built, and therefor will trigger an error.
- The binary release of 0.1.0 does not seem to be the same as that of building 0.1.0. This should be obvious, since the binary is 2 years old, but the version number is the same. Executing `install.sh` from the binary release on JanusGraph 0.5.2 resulted in a broken `gremlin.sh`. Building the repository then executing `install.sh` fixed this issue.
- Is the compatibility matrix in the description of binary release 0.1.0 outdated? At first I thought it was, being that it's a 2 year old release, and README.md claims version 0.1.0 can be used with newer versions of JanusGraph. But since it broke `gremlin.sh`, whereas the built version did not, perhaps it isn't outdated, and the version for the current state of the adapter should be bumped? Either that or the compatibility matrix for the release should be removed, as it conflicts with what the README says.
- README claims there are multiple binary releases, however there is only a single one.

I love JanusGraph and FDB and would love to use them together, but so far I've had no success, and following the README left me with little confidence that this adapter is ready. I feel there must be some user-error that's causing me issues, but I'm finding it hard to pinpoint. Either way, I feel new users could benefit from better documentation. I'm happy to provide dockerfiles to demonstrate any of the above mentioned issues.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reviewing README.md and install.sh, then compare their release, installation, and compatibility claims with the available binary release and built output described in the issue. Done means the documentation accurately describes supported versions and releases, and installation behavior and known prerequisites are clear to new users.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, shell
Domain
build-system, documentation, release
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.