The application documentation needs an overhaul

[serpens24]

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]

Also add in some help as a result of #696

[cygnus-x-1]

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

[antares1470]

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

[antares1470]

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]

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]

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]

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

[GammaVel]

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]]

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]]

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