I've been experimenting with OrientDB recently and as one would expect reading the documentation. In general I'd say that the quality of the documentation is of a fairly high quality, especially for such a young project. As I've been experimenting with and learning more about OrientDB I thought that I might try to contribute in whatever limited way possible. Seeing as I find myself digging through the documentation on a fairly regular basis I thought that editing and expanding those docs might be a good way to contribute.
I feel that my *not* being an OrientDB engineer could be helpful when it comes to documentation as I'm not so familiar with the topics at hand that I assume the reader is already familiar with the underlying subject matter. Also, I am a native English speaker (unfortunately, English is the only spoken language I'm familiar with) and that seems to be the language that Orient is targeting initially. While the current GitBook[0 <https://www.gitbook.com/>] based documentation is reasonably effective and attractive I find myself wondering if a tool such as Sphinx[1 <http://sphinx-doc.org/>] and potentially by extension Read the Docs[2 <https://readthedocs.org/>] which is based on Sphinx might be a better way forward. Sphinx is capable of consuming and rendering the current GitHub flavor of Markdown[3 <https://help.github.com/articles/github-flavored-markdown/>] based docs that OrientDB's documentation is written in as well as the arguably more rich reStructuredText[4 <http://docutils.sourceforge.net/rst.html>]. Beyond markup, Sphinx is also capable of integrating with the JavaDoc[5 <http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html>] based documentation that OrientDB already utilizes[6 <http://orientdb.com/javadoc/latest/>] via the javasphinx[7 <https://bronto.github.io/javasphinx/>] extension. Sphinx is also fully internationalizable[8 <http://sphinx-doc.org/latest/intl.html>] such that while English may be the initial language any other language could be added as skilled translators become available. Aside from online HTML documentation, Sphinx supports output to various other formats including ePub (ebooks), Texinfo (Docbook and DVI), man pages, Microsoft Windows help files, plain text, and likely others. Would porting the OrientDB's existing documentation to Sphinx or some other documentation generator be something that Orient Technologies and the community would be interested in? Thank you for your time, Adam Hunt [0] https://www.gitbook.com/ [1] http://sphinx-doc.org/ [2] https://readthedocs.org/ [3] https://help.github.com/articles/github-flavored-markdown/ [4] http://docutils.sourceforge.net/rst.html [5] http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html [6] http://orientdb.com/javadoc/latest/ [7] https://bronto.github.io/javasphinx/ [8] http://sphinx-doc.org/latest/intl.html -- --- You received this message because you are subscribed to the Google Groups "OrientDB" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. For more options, visit https://groups.google.com/d/optout.
