Uploaded image for project: 'IGB'
  1. IGB
  2. IGBF-3152

Update/Create IGB endpoint documentation

    Details

    • Type: Documentation
    • Status: Closed (View Workflow)
    • Priority: Major
    • Resolution: Done
    • Affects Version/s: None
    • Fix Version/s: None
    • Labels:
      None

      Description

      Situation: As we continue to add additional endpoints to IGB (see IGBF-3131) we need to update/create documentation within the users or developers guide for using the endpoints.

      Task: Update/create documentation for the various IGB endpoints. Documentation should probably be in the IGB users guide, but may also need to look at developers guide. See comments in IGBF-3131.

        Attachments

          Activity

          Hide
          ann.loraine Ann Loraine added a comment -

          Perhaps the scope of this issue can be expanded to include checking and releasing documentation describing the App Store endpoint information.

          Currently, we have semi-private (non-advertised) documentation in this IGB App Store google drive folder, here:

          Google Drive > IGB Project Documentation and Plans > IGB App Store Project > Appstore Endpoints

          Here is a direct link to a document we used to develop the endpoint and communicate its interface to the developers working on the App Store project:
          https://docs.google.com/document/d/1FZoZmN603b2bCVVjAU2gS5i8DKG5qutagwkvPQZ0T48/edit?usp=sharing

          Show
          ann.loraine Ann Loraine added a comment - Perhaps the scope of this issue can be expanded to include checking and releasing documentation describing the App Store endpoint information. Currently, we have semi-private (non-advertised) documentation in this IGB App Store google drive folder, here: Google Drive > IGB Project Documentation and Plans > IGB App Store Project > Appstore Endpoints Here is a direct link to a document we used to develop the endpoint and communicate its interface to the developers working on the App Store project: https://docs.google.com/document/d/1FZoZmN603b2bCVVjAU2gS5i8DKG5qutagwkvPQZ0T48/edit?usp=sharing
          Hide
          ann.loraine Ann Loraine added a comment -

          Another possible scope increase: try to find more user-friendly documentation platform:

          • Something free that we can leverage to avoid having to maintain our own site - free Atlassian platform? (Confluence cloud?)
          • Read the docs ?
          • Something that can be version-controlled easily but is also easy to edit
          Show
          ann.loraine Ann Loraine added a comment - Another possible scope increase: try to find more user-friendly documentation platform: Something free that we can leverage to avoid having to maintain our own site - free Atlassian platform? (Confluence cloud?) Read the docs ? Something that can be version-controlled easily but is also easy to edit
          Hide
          nfreese Nowlan Freese added a comment -

          Here is the page I have created listing the IGB endpoints: https://wiki.bioviz.org/confluence/display/igbman/IGB+Endpoints

          Show
          nfreese Nowlan Freese added a comment - Here is the page I have created listing the IGB endpoints: https://wiki.bioviz.org/confluence/display/igbman/IGB+Endpoints It seems like we could move https://wiki.bioviz.org/confluence/display/igbman/Controlling+IGB+using+IGB+Links and https://wiki.bioviz.org/confluence/display/igbdevelopers/Bookmark+REST+API to be child pages for the IGB endpoints, as they describe in additional detail the parameters required for those endpoints (note that the Bookmarks confluence page is in the IGB developers space). Some of the endpoints seem redundant - igbGalaxyDataView, UnibrowControl, and IGBControl appear to all do the same thing. IGB link parameters user's guide page is blank: https://wiki.bioviz.org/confluence/display/igbman/IGB+link+parameters . The Controlling IGB using IGB Links page is the parent and describes the UnibrowControl endpoint parameters, which I believe are the same as the IGBControl parameters defined in the https://wiki.bioviz.org/confluence/display/igbdevelopers/Bookmark+REST+API page. We may be able to remove the empty page.
          Hide
          nfreese Nowlan Freese added a comment -

          Here's a blog listing various documentation tools: https://document360.com/blog/software-documentation-tools/

          Show
          nfreese Nowlan Freese added a comment - Here's a blog listing various documentation tools: https://document360.com/blog/software-documentation-tools/
          Hide
          nfreese Nowlan Freese added a comment -

          I made the changes discussed during scrum and added some additional formatting.

          I decided against moving the other pages (Bookmarks and IGB Links). I added a link in the Bookmarks page to the endpoints page. The IGB Links page has been available for a long time and it may be confusing for users to find the page if I turn it into a child of IGB endpoints. I have also included links to both pages from within the IGB endpoints page.

          To test:
          Please review the IGB endpoints page page.

          Show
          nfreese Nowlan Freese added a comment - I made the changes discussed during scrum and added some additional formatting. I decided against moving the other pages (Bookmarks and IGB Links). I added a link in the Bookmarks page to the endpoints page. The IGB Links page has been available for a long time and it may be confusing for users to find the page if I turn it into a child of IGB endpoints. I have also included links to both pages from within the IGB endpoints page. To test: Please review the IGB endpoints page page.
          Hide
          ann.loraine Ann Loraine added a comment -

          Documentation is great. Moving to Done.

          Show
          ann.loraine Ann Loraine added a comment - Documentation is great. Moving to Done.

            People

            • Assignee:
              nfreese Nowlan Freese
              Reporter:
              nfreese Nowlan Freese
            • Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: