ArangoDB Doc - Integration

[sleto-it]

• Initial PR to integrate the ArangoJS doc into the ArangoDB official doc, using a sync mechanism

• The doc will be edited in this repository, and copied (by the sync script) in the ArangoDB official doc

• Creates some folders for the integration, plus two folders for the doc ("Getting Started" and "Reference")

• Further improvements can be done - this is a first PR

• Internal Reference:

  • https://github.com/arangodb/planning/issues/1736
  • https://github.com/arangodb/planning/issues/1504

• Public Issues:

  • Migrate API docs to GitBook/alternative? #123

[pluma]

Is the folder structure necessary? It doesn't make sense to have the full structure in this repo:

docs/Drivers/JS/GettingStarted/README.md

The "Drivers/JS" part is redundant. Can the integration still work if we use "docs" as the root instead?

[dothebart]

Hi @pluma,
the Idea was to replicate the structure under Documentation/Books/ so several targets can be addressed.

There is going to be a new Drivers Book, which is why we have Drivers here. The documents are to be placed in js which is why this has a place in the path.

[pluma]

@dothebart I understand that but the structure is highly redundant outside that specific context. This is a standalone repository for the arangojs driver. There aren't going to be any other driver docs in this repo. Is it possible to adjust the script so it knows to copy the arangojs docs folder into docs/Drivers/JS for the unified documentation?

Having two redundant layers of nesting in this repo increases the potential for errors, is confusing and makes maintenance more difficult.

[dothebart]

You have to see the whole picture - It will not only be like this in this driver repo, but in any driver repo.
Once the structure is established (this pr accepted), you won't make this mistake anymore.

The alternative to this approach is to remove the documentation entirely over here, and only maintain it in the ArangoDB main repository.

[sleto-it]

Hi all,

I understand the full structure is redundant - we are trying to do the best to improve things (having the new book). Please let's accept the needed compromises, there always be ways to improve things

Thanks,

[pluma]

I've rebased the PR and copied some of the content back into the README to make the yarn/npm package descriptions less useless. Let's see how this works out.

[sleto-it]

many thanks @pluma - appreciated