Needs hierarchal structure and tocs

[wayne-werner]

It's nearly impossible to find what one is looking for.

[lvca]

The documentation is hosted on: http://orientdb.com/docs/last/. Are you using this as documentation? This is only to contribute to it.

[wayne-werner]

Ah... then I guess that the doc build process should be part of the docs then... contributors/reviewers need to be able to look at the proposed changes in situ, not just the latest release. How often is 'latest' updated?

It would also be important to branch and label so that one can at least generate the docs for the actual version of the software being used.

BTW, contributors need to browse the docs as well, and a toc hierarchy is the usual manner to do this. The docs are as important as the code and should be managed at least as tightly. For instance, any check in of code should have code changes/additions, tests and any supporting documentation additions or changes. Of course many bug fixes don't require doc changes. But every feature change and addition or deletion certainly does.

If you look at really successful open source projects like django and python for instance, the documentation is a first class artifact, not an afterthought.

[wayne-werner]

I know I wasn't clear on this... I should be able to check out a doc version, run the doc build scripts that come with the docs, and have a local doc site in html built on my machine. The toc hierarchy should be defined as a folder hierarchy, not as some sort of toc master file configuration in the build process.

[wayne-werner]

An additional note: I don't really understand why one would complicate things with a separate repository for docs, and not a docs folder in the code repository. That makes doc and code releases butt simple to keep in sync moving forward.

[santo-it]

Hi @wayne-oscme,

Thanks for opening this issue and for your feedback

I do agree with you about the importance of having table of contents

In the latest doc version (http://orientdb.com/docs/last/) we have added a toc in each page (the commit is https://github.com/orientechnologies/orientdb-docs/commit/70721c149a623a163b0aef75beeaec829cdc8365)

To reply to one of your questions: the documentation is updated about every 15 minutes. Please try also the “search” box in the top-left corner: it should help in case you are looking for something specific

There is a combo-box at the top-left corner that allows you to select the version of the documentation you want to read, e.g. last, 2.2 or 2.1

I do agree with you about the importance of the documentation in an open source project. Thanks for your patience while we work to improve our documentation

You have posted lot of feedback on this issue (thanks again!). My suggestion would be to split different topics on different issues: this will surely help us, especially because different issues can be resolved at different times

Now that tocs have been added, I’d probably suggest to close this issue and open new issues for other feedback or problems, if they are still current

Hope this helps and thanks again!