Here are my comments, mostly from a documentation engineering perspective. I fully recognize that not all of these questions can be answered before the document is baselined, but I do want to initiate a broader conversation about documentation design.
By the way, the design for a contextually adaptive search form sounds really impressive. It sounds like IntelliSense, but for a search form.
Section 3.2.1 Context-Dependent Help
I really like the emphasis on UX and contextual information discovery here.
A general industry term for "naming and labeling of UI elements and screens" is "microcopy" and I absolutely agree in the value of a good, coherent microcopy strategy.
Another thing we might consider under context-dependent help is the onboarding experience. The idea here is that we'll plop a brand new user in front of a portal search form, but can we tip that user in the direction of starting to make a useful query and exploring data? Tool tips contribute to the "reference" aspect of a documentation ecosystem, but they're not necessarily a replacement for tutorials that lead the new user through the product. A big thing in app design these days, that we all see, is a guided in-app onboarding experience. Should we do something similar? (There might be a good collaboration with EPO here to share knowledge about designing and implementing onboarding experiences).
Section 3.2.2 User Guide
In this section, I'd back away from the phrase "It will grow, with user feedback, to contain additional information of a 'FAQ' nature [...]" Yes, user feedback is critical for developing documentation, but we should not baseline "FAQ" as an information architecture. In the tech writing community, "FAQ" is often considered a synonym for documentation that has no architecture. All DM user guides have an information architecture. These IAs are based on the concept of topic-based writing (cite https://everypageispageone.com/the-book/) with intentionally-designed topic types that fit into the quadrants of concept guides, tutorials, how-to guides, and reference guides. https://dmtn-030.lsst.io is an example of information architecture design for a user guide (though it still needs work to develop) and I expect that the Science Platform user guide will require at least the same level of IA design treatment.
What is the relationship between the Portal deployment and the user guide deployment? Is the Portal user guide hosted within the Portal web application itself? That is, do I need to start thinking of the Portal as a new content management system for a user guide? I think I saw from from an IRSA deployment that the user guide is part of the portal application itself. Is that our assumption here too?
My main reason for asking about this is that I want to design a coherent user documentation system across all DM products. I know that section 3.2.2 necessarily talks about just the Portal documentation, but I think it's more productive to think about the LSP user guide as a whole, instead of starting from the architectural components. Just off the top of my head, after reading LDM-532, the LSP user guide needs to cover these services:
- Portal search and visualization services
- Customized workflows in the Portal
- User space (from all aspects)
- Batch service (from all aspects)
- Mini broker service
- JupyterLab environment in general
- Data access from the notebook environment and data processing tutorials (cross linking into pipelines.lsst.io documentation)
- Public HTTP APIs including all the TAP, SIA, and SODA.
(This list certainly isn't exhaustive and necessarily well-organized or phrased, the point is that the user guide covers the full breadth of the LSP's user-facing features).
Deployment-wise, my preference is to implement the LSP user guide with the same static-site-centric infrastructure we're building for all other LSST DM user guides. And specifically, that we don't make the Portal user guide deployment a special case because I think that could complicate the information architecture and reduce coherence.
Another question that needs to be resolved is the information architecture that surrounds the LSP user guide, and the Portal itself. As you say, "How much broad summary information may be provided to unauthenticated users through the Portal itself — e.g., documentation on the LSST project, a summary of the progress and coverage of the survey — versus through other public faces of the Project is yet to be determined." In other words, to what extent is the Portal the LSST "homepage" for all astronomers? I think this is a great question.
Related to this this, I'm also wondering about the relationship between the LSP documentation and data documentation. For example, I'm thinking that there will be separate "user guides" for each data release that provide references for tables and columns, descriptions of the processing pipelines (cross linking to Task documentation in pipelines.lsst.io) and data characterizations. But as a project, we haven't formalized this yet.
Formalizing this information architecture is important because it will allow us to begin designing the system for contextual documentation links you describe in section 3.2.1.
Section 3.2.3 Reference and Deployment Manuals
If my interpretation is right, I'd suggest renaming the section to be "Development and Operations Guides" and mention that it will contain references for internal Science Platform APIs. That is, the intended audience for this guide are those that develop the Science Platform codebase, and deploy the Science Platform services.
Integrating the Science Platform with Science Literature
What capabilities does the Science Platform provide for those who are publishing their science results?
- Can an astronomer use the Science Platform as a backend for a table/dataset that is published in a journal article?
- Can an author publish or reference the search query they used to obtain a dataset (before applying their custom pipelines to further filter and transform the data)?
- Can an author publish (as a static, read-only view — but maybe forkable too) the notebook they used to arrive at a result?
More general comments
These comments are mostly to clarify what isn't part of the design:
- I don't see any mention of accessibility. Is intentional design for accessibility just not something we'll do?
- Will the Science Platform allow for internationalization in its UI microcopy?