The application documentation needs an overhaul

serpens24 commented 4 years ago

Prerequisites

[x] Put an X between the brackets on this line if you have done all of the following:
- Running the latest version of Constellation
- Attached the Support Package via Help > Support Package
- Checked the FAQs: https://github.com/constellation-app/constellation/wiki/FAQ
- Checked that your issue isn't already filed: https://github.com/constellation-app/constellation/issues
- Checked that there is not already a module that provides the described functionality: https://github.com/constellation-app/constellation/wiki/Catalogue-of-Repositories

Description

The current state of Constellation's documentation is rather poor. Some of the issues I've identified include:

documentation of the graph itself is somewhat outdated and fails to include some of the more recent functionality additions.
schemas are completely undocumented.
the plugin framework is completely undocumented.
several import/export tools are completely undocumented (google earth, shapefile, image, etc).
several arrangements are completely undocumented (hierarchy, proximity, spectral, etc), and some of those that are documented are done so in an extremely poor manner (bubble tree).
several tools are completely undocumented (document clustering, hierarchical clustering, complete with schema, external scripting api, composite nodes, etc).
several views are completely undocumented (histogram, schema view, scripting view, etc).
the attribute editor documentation is lacking any real information, and there still exists a help page on the now non-existent attribute value editor (under graph > editing > edit attributes).
named selections documentation is in the wrong category (in graph, should be in views).
there is no consistent style or formatting across documents (header styles differ, font sizes differ, many images are poorly aligned, poorly sized, or stretched out, etc).
Add missing help pages
Help topics for data access view categories Help topics for data access view categories were requested. These would only need to be very brief. Consider using tool tips here

Suggested the Analytic view help could appear similar to the DAV or Schema View

Could include pre-requisite information of how the graph should be structured before running some analytics
The help documentation could include example graph diagrams to help explain how they work
Some of the help documentation is still too technical

I believe this poor presentation will create a bad first impression for anyone learning to use the application and should be completely overhauled.

Expected behaviour: Documentation is as complete as possible and make it as easy as possible for new users to use Constellation.

Actual behaviour: Documentation is out of date and incomplete.

Reproduces how often: 100%

Additional Information

Help pages to review/update: Overview

[x] About Constellation
[x] Getting Started
[x] The Graph Window

Graph

[x] The Constellation Graph Model
[x] Attributes
[x] Types
[x] Expressions Framework
[x] The Constellation File Format
[x] Example Constellation File Reader
[x] Example Constellation File Writer
[x] Autosave
[x] Nebula
[x] New Graph
[x] Open Graph
[x] Save Graph
[x] Add and Selection Modes
[x] Cut, Copy, Paste
[x] Decorators
[x] Icons

Selection

[x] General Selection
[x] Blaze Selection
[x] Dimmed Selection
[x] Structure Selection
[x] Induced Subgraph
[x] Hop Out
[x] Shortest Paths

Tools

[x] Compare Graph
[x] Merge Nodes
[x] Chinese Whispers
[x] K-Truss

Jupyter

[x] About The Jupyter Notebook Server
[x] About The Constellation REST Server

Views

[x] Analytic View
[x] Connects the Network Nest?
[x] Has Closest Relationship?
[x] Most Central?
[x] Most Communicants?
[x] Most Easily Reached?
[x] Most Influential
[x] Most Likely Correlated?
[x] Betweenness Centrality
[x] Closeness Centrality
[x] Degree Centrality
[x] Eigenvector Centrality
[x] HITS Centrality
[x] Katz Centrality
[x] Pagerank Centrality
[x] Average Degree
[x] Component Count
[x] Global Clustering Coefficient
[x] Graph Density
[x] Graph Distance
[x] Connectivity Degree
[x] Eccentricity
[x] Effective Resistance
[x] Local Clustering Coefficient
[x] Multiplexity
[x] Ratio of Reciprocity
[x] Weight
[x] Adamic-Adar Index
[x] Common Neighbours
[x] Cosine Similarity
[x] Dice Similarity
[x] Jaccard Index
[x] Levenshtein Distance
[x] Preferential Attachment
[x] Resource Allocation Index
[x] Attribute Editor
[x] Conversation View
[x] Data Access View
[x] Data Access View: Options
[x] Extract Types from Text
[x] Extract Words from Text
[x] Import Graph File
[x] Merge Nodes
[x] Merge Transactions
[x] Remove Nodes
[x] Remove Unused Attributes
[x] Split Nodes Based on Identifier
[x] Test Parameters
[x] Datetime Range
[x] Select All
[x] Select Top N
[x] Find and Replace
[x] Histogram
[x] Layers View
[x] Map View
[x] Day / Night Layer
[x] Heatmap Layers
[x] Paths Layers
[x] Thiessen Polygon Layer
[x] Info Overlay
[x] Tools Overlay
[x] Overview Overlay
[x] Named Selections
[x] Notes View
[x] Perspective Bookmarks (Experimental)
[x] Plugin Reporter
[x] Quality Control View
[x] Scatter Plot
[x] Schema View
[x] Scripting View
[x] Table View
[x] Timeline
[x] Word Cloud View

Preferences

[x] Application
[x] Data Access Category
[x] Developer
[x] Graph
[x] Online Help
[x] Label Fonts
[x] Proxy

Arrangements

[x] Grid
[x] Line
[x] Circle
[x] Tree
[x] Hierarchy
[x] Node Attribute
[x] Scatter 3D
[x] Sphere
[x] Flatten Z Field
[x] Contract Graph
[x] Expand Graph
[x] Layer by Time

Import/Export

[x] Import From File
[x] Import From Database
[x] Export From Constellation

Help Pages to add

[x] Hierarchical Clustering
[x] Info Map Clustering
[x] Select Nodes
[x] Select Transactions
[x] Complete with Schema
[x] Composite Selected Nodes
[x] Composite Correlated Nodes
[x] #2087
[x] Proximity Arrangement
[x] Bubble Tree 3D Arrangement
[x] Proximity 3D Arrangement
[x] Spectral 3D Arrangement
[x] HDE 3D Arrangement
[x] Uncollide Arrangement
[x] Pin/Unpin Nodes
[x] Error Report
[ ] Point Marker Error Region (Experimental) Layer (Map View)
[x] Visual Schema
[x] Analytic Schema

Other

[ ] The Plugin framework

arcturus2 commented 4 years ago

Also add in some help as a result of #696

cygnus-x-1 commented 3 years ago

The Map View documentation should make it clear that the Latitude, Longitude or Shape attributes are required before anything will be rendered.

antares1470 commented 3 years ago

Core Data Access Plugins and views accessible via the Views menu (+ Notes and Layers Views) have now been updated

antares1470 commented 3 years ago

I've updated ticket to more easily track the progress of help page updates. I've haven't done an extensive look at what features are missing help pages (have currently only listed ones I recall) so that part of the list will likely be updated in the future with ones I've missed

GammaVel commented 3 years ago

The JDB help file has the following text that needs to be fixed up, noting that JDBC is one of the pages identified above

GammaVel commented 3 years ago

I've confirmed that the JDBC help text has been addressed as part of Release 3.4, the above comment has been addressed, thanks!

GammaVel commented 3 years ago

Thanks very much @antares1470 for making those help guide improvements. Really appreciate the updates :-)

GammaVel commented 3 years ago

hi, I noticed on the updated icons page under Visualisation there is a very small typo with colour. Everywhere else it has the american spelling so might be good to be consistent:

github-actions[bot] commented 1 year ago

This issue is stale because it has been open for 6 months with no activity. Consider reviewing and taking an action on this issue.

github-actions[bot] commented 10 months ago

This issue is stale because it has been open for 6 months with no activity. Consider reviewing and taking an action on this issue.

HolandCrick commented 2 months ago

@antares1470 - thanks for updating the help pages. It's looks great now.

constellation-app / constellation