neo4j
Documentation Improvements
- Go over the docs and consolidate, fix rendering issues
- Inline "overview.adoc" into the appropriate places
- Add larger topic sections that structure the individual areas better
- Add deprecations notices and a deprecation section for larger chunks
Sections
Schema
- visual schema
- tabular, document schema
- index schema
Data Integration
-> Export/Import -> CSV/JSON/XML/XLS/GRAPHML -> Databases -> RDBMS/Mongo/ES/Couchbase/Bolt -> Geospatial
Conversion
- datetime
- number
- json
Graph Refactoring
Path Finding
- Expand
- Path Algorithms
Virtual
- Virtual Nodes and Relationships
- Grouping
Utilities
- Numeric, Text, Map, Coll, Hash
- Bitwise
- BigInt
- Atomic
Cypher Execution
- Job Management
- Triggers
- Cypher Execution
- Custom Procedures
Operational
- Cypher Initializer
- Davids
- Monitoring
- Config
- Warump
Indexes (deprecate)
- Fulltext Index
- Manual Index
Having a section of APOC docs that are sort of like a FAQ would be useful. For example, people use apoc.periodic.iterate to overcome OOMEs. They don't search for apoc.periodic.iterate, they search for solutions to OOME.
So a very short "cookbook" would be nice.
- Have problem X? Look at apoc.foo.whatever();
- Have problem Y? Look at apoc.bar.magic();
Second idea -- curated blog posts. A lot has already been written about APOC. Some probably has aged out of usefulness. Some might get referred to a lot by people. Help boost the non-APOC documentation by linking useful resources for further learning / tutorials. This gives more official stance to the best blog posts, and drives more traffic to them, improving APOC documentation and understandability without changing much.
Third idea -- "apprentice tasks". Some good open source repos I've seen have issues that are filterable by "how hard is it to do this". They have some small documentation tasks as apprentice tasks because it's an easy approachable way for someone new to contribute without knowing all the stuff really deep. So one thing to improve collaboration is don't write all of the docs, but have a list (like what you have here) that's always available so a newbie can tackle a simple issue, learn more, and contribute. "Wantlist" for documentation if you will.
Thanks for opening this issue, @jexp. I'll look into adding a note about byte caps on indexed properties.
As we gonna deprecate/remove those soon, not sure if that makes such a difference. But happy to add it.
Ah, gotcha. I somehow missed that at the bottom of your first post.
I updated the docs to be chunked into the sections mentioned above. You can find the new variants here:
http://neo4j-contrib.github.io/neo4j-apoc-procedures/3.5/
@moxious should we collect relevant blog posts here?
Do you think more individual posts or whole blogs? I think a number of the KB articles also use APOC frequently.
I wonder if we should link them directly in the docs or use some other means of curation?
I'm also not 100% sure if we want to have the reader, go read those blog posts themselves or if we should provide a 1-2 sentence summary so they know if it's relevant.
Possible blogs:
- https://medium.com/neo4j
- http://www.jexp.de/blog
- https://tbgraph.wordpress.com/
- https://maxdemarzi.com
- https://blog.bruggen.com
- https://www.adamcowley.co.uk/
- https://info.michael-simons.eu/tag/neo4j/
And possibly a number more.
I'm not sure on how best to curate. Ideally we would have a subcategory of the neo4j medium or something like that, and then when a blog post is really good it gets copied/promoted there but then it loses some of its link authority and it's also a lot of work. The issue is that this content is very spread out from the beginning.
Definitely when including a blog post it's good to have a one-sentence summary of what it covers.
Personally I think the best way to organize it is probably around a "FAQ for Neo4j" because this is sort of how APOC evolved. Structure it as a problem solving guide for Neo4j. We could also start a community thread where we ask people what challenge they ran into and how APOC solved it, and curate the best from this because we know it's happened quite a lot.
This seems way out of date and beyond documentation anyway. If any of this highly important will come back in more concrete and uptodate form.
