Documentation in the dashboard

[johrstrom]

As we search for and contemplate a new way of creating documentation, it's becoming increasingly clear to me that having the documentation inside the OnDemand app (specifically in the dashboard) is the best option.

• No need to learn new technologies and frameworks. Docusouras, VuePress, MKdocs, even Jekyll have some learning curve to them. If we build the docs in Rails, there's no need to need to learn anything new. In fact, it may increase the Rails skills of our team!
• Documentation inside the app can tell you if a feature is enabled. Imagine this use case: You're reading a recipe for app development. The page within the dashboard can directly whether you have development enabled and if you're enabled as a developer. This is the same for almost any feature. In the documentation itself - it can tell you the state of your site, whether you're using a default or what you're current configuration is!
• Recipes and examples use the same code base as the actual product. Imagine this use case: A recipe for editing a select drop-down menu. The example yaml (maybe the entire example app) exists within the documentation, and the views are generated with the same library as the actual interactive apps. So, the dropdown in the example is an actual select box you can interact with! As a late game enhancement maybe even these recipes and views are editable so the recipe is then interactive.

• Static Pages POC - Documentation #4050
• Global Search Bar to Documentation #4049

┆Issue is synchronized with this Asana task by Unito

[ndusek]

I was pointed here from this thread on the discourse site. I think being able to create documentation in the OOD dashboard would be great, especially for things like training and tutorials. Hope this is still being worked on!

[AshASML]

I'm looking to create documentation ,more like HTML static page in OOD dashboard. Will this help https://osc.github.io/ood-documentation/latest/customizations.html#custom-pages or this feature is still worked on ? Any update here would be appreciated . Thanks!

[johrstrom]

Sorry this is more about replacing the documentation here: https://osc.github.io/ood-documentation/latest/ with documentation that's in the application itself. I just navigated to the help tab in outlook for example. Their help docs are in their application, as well as being online. That's what this ticket is about - moving our OnDemand documentation.

I think you're all wanting is as a site administrator to be able to add documentation pages which is more along the lines of #940.

Having said that, I think that custom pages is an excellent way to do this until we make it easier.

[AshASML]

Thanks for your response.
I believe that #940 could be helpful in this case as I'd want to multiple nested pages in the user documentation and ability for the users to navigate and choose the pages he wants to read. Can you tell me if I can achieve this using custom pages?
Example of what I want to achieve:

[johrstrom]

Can you tell me if I can achieve this using custom pages?

I'd have to inspect the HTML and replicate it. Bootstrap 4 is available to your custom pages. I'm sure that's some combination of ul, li and a tags.

[AshASML]

Got it , Thanks !

[johrstrom]

I think what I'm looking to replicate is something like MATLAB does documentation.

You can see here there's a search bar in the app itself to search for docs that then appear in a new window:

And that right clicking the function figure opens this menu bar which allows you to go straight to the documentation for that function:

[johrstrom]

And I have to admit that this is a little bit of a moonshot in the sense that it's a whole lot of work.

[johrstrom]

Sadly I had an inkling of how this could play out with a gist on github that I cannot now find.

I'll continue to look for that gist, but the premise of what I'm thinking is basically:

• Have a static Rails.env
• Boot the application in the static environment
• have some rails task to request/curl all pages and store them
  • This likely needs to sed/search/replace to correct all the hrefs

The gist was an example of the 3rd step.

Edit:

Maybe I found it? https://gist.github.com/sc0ttman/1041602

[johrstrom]

Sadly, I'm not sure if this is even a good idea. I think we're kicking this to the backlog because (a) it's very hard to implement and (b) there are higher value things we can do now instead.