search

florinpatrascu / bolt_sips

Neo4j driver for Elixir
Apache License 2.0
256 stars 49 forks source link

Documentation: public / private / guides? #62

Closed dominique-vassard closed 4 years ago

dominique-vassard commented 5 years ago

Hi, As project grows, document does too. I found current Hex documentation a little bit messy and it doesn't help user to leverage the true power of bolt_sips.

What can we do?

What do you think,

florinpatrascu commented 5 years ago

Hi Dominique - the documentation is indeed lacking and we'll have to clean it up. It's mostly my fault for just documenting the code I was writing, thinking the driver will not become more than a simple toy a user could use for learning Neo4j & Elixir :) As time passed it became more complex and its applicability today goes beyond a simple ... mix task ... one could use for playing with Neo4j and learn Cypher.

To address your points:

For the documentation, I was already contemplating a different medium i.e. GatsbyJS? This is a similar approach Distillery took when they realized the "Readme" can't just be the official docs, anymore.

Probably the easier path from all of the above would be just to use ExDoc's abilities better, as a start?!

dominique-vassard commented 5 years ago

I do like docs with example and explicitness everywhere, that usually makes me want to use the thing and believe the thing is great. And as bolt sips is different from other Neo4j driver, an extensive doc is mandatory event for Neo4j "senior" users. I don't think we anything but Hex for doc for now but why not an external site if it's not a considerable amount of work. The distillery example is a good one: as I saw, it's just simple Markdown as we should do for Hex, so no extra work needed :)

dominique-vassard commented 5 years ago

GatsbyJS looks a bit overpowered for our needs. It's highly customizable yes but I'm more into simpler alternatives, which are still very efficient like mkdocs or docsify.

florinpatrascu commented 5 years ago

I honestly looked at it first because I like shiny things :) I am sucker for good fonts, clear layouts and natural color palettes; spending lot of time customizing my Terminal, editors and so on. But the most important aspects I was looking at when reading about GatsbyJS, were: publishing and the ability to write markdown. Both being very well supported, by GatsbyJS.

Publishing is so easy too. One click and the github repo containing the docs can be up in seconds, on Netlify (and similar)

However, I didn't spend much time on reading too much from its docs, which is a shame, there are only so many weekends in a year :( Therefore I might've overlook some aspects that could bite us later .. I don't know 🤷‍♂️

florinpatrascu commented 5 years ago

few thoughts - working at the routing part these days, I realized how much we need to work for bringing the documentation where we want it to be. And the new functionality will only add more docs to the exiting ones. Let's stay with the support we have in the language itself; module docs, doctests, readmes and eventually a folder with examples and their associated go-through mini-guides. At least the users will be able to use hexdocs for finding the answers they need, w/o needing to go to a different server for them. Later, when the new driver will be released, and if any kind souls would like to help us with creating a better support for documentation, then we can focus on that at that time :)

florinpatrascu commented 4 years ago

the documentation will be hosted by HexDocs