Refinement of survey responses - documentation

[bertfrees]

We are currently in the process of analysing your responses to the Pipeline usage survey held earlier this year. Some of the feedback requires some more elaboration or discussion. Below are some responses in the topic "documentation":

---

• Q: Strategic comments/questions about Pipeline
  • One organisation would like better documention about the connection between Pipeline 1, Pipeline 2 and Save-as-DAISY:

    It would be great to have some document that can summarise in a more popular way how to use Pipeline 1 and 2, the actual differences, the connection with Save As Daisy. Maybe something about the fact that Pipeline 1 isn't updated anymore although many organization are still using it because they can't find scripts that fits their need in the Pipeline 2.

• Q: Would you like any help, advice or guidance about starting to use Pipeline in your organization?
  • One organisation requested better documentation on Docker:

    Simple tutorials on getting started with the Docker based pipeline. Every system in our IT architecture is Docker based, so that's the form we would prefer to test and review the pipeline for potential use.

• Q: How easy has it been to integrate Pipeline into your production workflow?
  • One organisation commented about the documentation of the web service:

    The documentation of scripts was/is mostly focused on uses in the GUI or CLI, so it took some digging to find the right parameters and values to submit through the API, and how to interpret the responses.

• Q: What do you think are the 3 greatest weaknesses of Pipeline?
  • One organisation mentioned complex documentation

---

I would like to know:

• What is missing from the current documentation on using Pipeline with Docker? Do you have suggestions?
• Do you have suggestions for improving the web service documentation?
• We would like more specific examples of complex documentation, and suggestions for how to make it simpler.

[josteinaj]

Maybe the Web API could be documented with OpenAPI? That makes it easier to explore using tools like Swagger and Postman.

[bertfrees]

@josteinaj That's interesting. I wonder whether this approach is compatible with Restlet, and how flexible this is.