neo4j / apoc

Apache License 2.0
85 stars 27 forks source link

Documentation Improvements #127

Open neo-technology-build-agent opened 2 years ago

neo-technology-build-agent commented 2 years ago

Issue by jexp Tuesday Feb 12, 2019 at 11:00 GMT Originally opened as https://github.com/neo4j-contrib/neo4j-apoc-procedures/issues/1093


  1. Go over the docs and consolidate, fix rendering issues
  2. Inline "overview.adoc" into the appropriate places
  3. Add larger topic sections that structure the individual areas better
  4. Add deprecations notices and a deprecation section for larger chunks

Sections

Schema

Data Integration

-> Export/Import -> CSV/JSON/XML/XLS/GRAPHML -> Databases -> RDBMS/Mongo/ES/Couchbase/Bolt -> Geospatial

Conversion

Graph Refactoring

Path Finding

Virtual

Utilities

Cypher Execution

Operational

Indexes (deprecate)

neo-technology-build-agent commented 2 years ago

Comment by moxious Tuesday Feb 12, 2019 at 18:01 GMT


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.

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.

neo-technology-build-agent commented 2 years ago

Comment by jexp Tuesday Feb 12, 2019 at 20:42 GMT


Great ideas, thanks a lot David!!

neo-technology-build-agent commented 2 years ago

Comment by myedibleenso Tuesday Feb 12, 2019 at 22:28 GMT


Thanks for opening this issue, @jexp. I'll look into adding a note about byte caps on indexed properties.

neo-technology-build-agent commented 2 years ago

Comment by jexp Tuesday Feb 12, 2019 at 23:31 GMT


As we gonna deprecate/remove those soon, not sure if that makes such a difference. But happy to add it.

neo-technology-build-agent commented 2 years ago

Comment by myedibleenso Tuesday Feb 12, 2019 at 23:45 GMT


Ah, gotcha. I somehow missed that at the bottom of your first post.

neo-technology-build-agent commented 2 years ago

Comment by jexp Sunday Feb 17, 2019 at 12:59 GMT


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/

neo-technology-build-agent commented 2 years ago

Comment by jexp Sunday Feb 17, 2019 at 13:18 GMT


@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:

And possibly a number more.

neo-technology-build-agent commented 2 years ago

Comment by moxious Sunday Feb 17, 2019 at 13:59 GMT


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.