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
• ADQL
• 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

In this section, what do we mean by "API documentation?" I think you mean internal APIs (i.e., non-public HTTP APIs, JavaScript APIs, etc). We're not documenting public APIs (like DAX's VO HTTP APIs) here, right? To me, those are part of the public-facing Science Platform user guide.

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?

Regarding the science literature question. I would love it if we formally adopted DOI support for science platform (similar to MAST) but it needs thought and discussion and buy-in from AURA (or at least NCOA).

Jonathan Sick, thank you very much for your very detailed and thoughtful response. I will respond in more detail later (I hope tomorrow) but there are a few points I'd like to make right away because they are important to me.

• Mentioning the FAQ explicitly may have reflected too much of a jaded vision on my part about the realities of virtually any collection of technical documentation for a large scientific computing project I've encountered. (Not just science: I don't think the VAX/VMS documentation needed a FAQ, it was so good out of the box, at least by VMS v4, but it's one of the few examples I can think of.) I suspect in the end we'll need a FAQ, but perhaps we shouldn't give away the point of principle just yet.
• I don't think we are tied to the IRSA style of deploying the Portal user guide. I think we will have "help icons" scattered around the UI, which will need to link directly to the relevant help text (more directly than the IRSA help currently does, though we are already starting to work on improving the deep linking there), but the organization of the pages to which those links point can be rethought for LSST.
• I care a great deal about accessibility and I should have mentioned it. However, I think this is going to require a lot of substantive work even to plan for, let alone implement, so if I had mentioned it I would have been at a loss for what specifics could have been given without a real design.
• I believe that internationalization was explicitly ruled out at some point in the past as beyond the funded scope, and I understood, in response to a question I explicitly asked, that we were not expected to produce a Spanish version of the Science Platform. Unfortunately we don't explicitly document "anti-requirements" so I don't quite know how to prove this. Perhaps Kian-Tat Lim remembers something about this?
• The Portal-centric nature of what I wrote is an artifact of the limited time available for consultation with the API and Notebook groups last summer; of course we should think of it as a unified system. I'd like to do a second round of work on this with you and RFC the resulting updates separately.

I very much wish we could do internationalization, for the record, given the long-lasting importance of LSST. Perhaps this is something that could attract private support at some point?

Regarding internationalization, can we design the system with internationalization in mind even if we have not added the other languages. I think I recall Fabio Hernandez or Dominique Boutigny saying that they would be more than happy to provide French translations if we had a system in place that could accept it. The mistake is to hard code all our text into the code.

Gregory Dubois-Felsmann once you feel the work on your ticket branch has been done, you can merge to master. We can then create an RFC ticket branch for last minute edits and the release.

lets get a version of this baselined

Further replies to Jonathan Sick's comments:

I think some of what you are writing about transcends the Science Platform and belongs in a higher-level document that describes an integrated documentation architecture, with the LSP Design document then edited to refer to the appropriate portions of that document, and then provide additional specific detail on how the LSP as a delivered product integrates with and implements parts of that overall design.

As you suggested, I think that should be part of a later revision to this document coordinated with the release of the higher-level document.

Re: 3.2.1 (Context-Dependent Help)

Regarding the on-boarding, and the provision of introductory material, I am strong believer in what you describe and will add a short mention to it in this version of the document, with a fuller description deferred to the update I proposed above. I think this is actually conceptually closer to being part of the User Guide, though delivered contextually through the UI.

I find the "sample queries" and tutorial videos this would involve very useful in similar systems. I do have some concern about whether we (DM as a whole) are adequately resourced to do a really superb job on producing it. Perhaps we could work together on trying to do an FTE-year estimate.

Re: 3.2.2 (User Guide)

As I noted in my initial response, I will take out the sort of defeatist language about the FAQ and incremental development of the documentation that you are concerned about.

Regarding the delivery of the User Guide and your question about IRSA, I'd like there to be a real document with a logical flow that one could, in principle, sit down and read end-to-end, but I would also like to be able to deep-link to relevant places in it from the appropriate places in the UI. I think this would apply to the Notebook Aspect as well. I don't think the current version of this document is committing us to whether it "looks like" the targets of those links are "in the Portal application" or part of some distinct LSST documentation system. I would very much like to have bidirectional links, so that if I'm reading the User Guide online, and it tells me about the - say - time series tool, I can click straight from the UG over to that tool and perhaps even have it come up with a sample query - ideally one that was also used to generate screenshots for the UG - ready to run.

As I said above, the limitation of scope to the Portal was just an artifact of the development process. Round 2 will require time and input from the API Aspect and Notebook Aspect groups to get them included, and again, should result in a documentation architecture that even transcends the LSP.

See also the "Data documentation" note that I shared with you and others last July. I'll put that somewhere where everyone can see it; it's relevant to the overall vision.

Re: 3.2.3 (Reference and Deployment Manuals)

Yes, "API documentation for both the client and server components of the Portal" means documentation on the APIs used within Firefly and similar components, not the DAX APIs. But they are not "internal" APIs - they are exposed on the public Internet and they are relevant to anyone who may wish to produce a custom Portal or to control the Portal remotely. They include JavaScript, Python, and network APIs, of which firefly_client is an example.

There are also true "internals" and I would also expect them to be documented (e.g., how the sharing of state across load-balanced instances of Firefly works). This would be part of the "Deployment and Maintenance Manual" that is mentioned.

I think this can start to be address by splitting this section into two: one for the user-facing reference manual, and one for the project-facing deployment, maintenance, and implementation manual.

Do you generally prefer the word "Guide"?

Re: Integration with science literature

Roughly speaking the answers to all three questions are "yes" but the planned facilities are relatively primitive. I think the answers to them belong in something more like an operations concept than in a design document - the design provides the relevant lower-level capabilities, which can be used to accomplish these goals - except for the notebook-forkability: we are not going to host a version control system, and assume that users will be happy to use their generation's version of Github if they wish to share a notebook in that manner.

Another caveat is that LSST is not currently funded or authorized to be a permanent archive with immutable links to users' published data, so although a user can publish a dataset on the LSP and link to it from a journal article, that may not be best practice if there is a more explicitly archival site available for them to do that. It would probably be good if LSST could take on such a role, given the usefulness of the tools we're building in such a context, but that's a question I can't address in LDM-542.

Re: accessibility

I repeat my above comment. We would need an explicit mandate to do so; it's not a small thing. It's not in our requirements. Personally, I think it's desirable, without question. If there is an entry level of best practice that we can follow to avoid carelessly obstructing the operation of browser-level accessibility tools like text-reading, we should do that; I'm not technically qualified to identify the necessary guidance. But I don't think we can go beyond that to the larger question of "what does it mean to provide accessible interfaces to astronomical data" without an explicit mandate and scope.

Merged March version to master and created tickets/RFC-467 branch. Applied Fritz Mueller's changes from tickets/DM-13724. Fine-tuned some text related to the User File Workspace.

Applied changes arising from Tim Jenness's review to the RFC branch as well.

I've applied what I can of changes arising from Jonathan Sick's review as well.

See:

• https://github.com/lsst/LDM-542/tree/tickets/RFC-467
• https://ldm-542.lsst.io/v/RFC-467/index.html

This is all the immediately doable work that I'm aware of and I think the document is ready to be released. Let's discuss at the DMLT telecon tomorrow.

I'm happy for this to be baselined. Wil O'Mullane did adopt this RFC.

Fully implemented: v1.2 of LDM-542 created and recorded as a baseline in Github and Docushare according to the developer.lsst.io procedures.