Documentation Workgroup meeting: October 7th, 2024

Apologies for not explicitly posting that the meeting was happening prior to it. That said, inlined at the meeting notes:

Documentation Workgroup, 7th October 2024

Attending:

  • Franklin
  • David
  • Daniel
  • Sven
  • Dave V
  • Sophia
  • Rauhul

Topics:

(Joe) Through the ContribEx workgroup, learned about some complications/issues the website work group. They're looking to adopt DocC as much as possible for documentation. Two/three feature requests:
- Ability to remove /documentation prefix in their documentation URLs.
- Better theming support.
- Linking between separate content units (what would be separate catalog builds of documentation)

The following are snippet from notes from the contribEx meeting, related to what Joe gathered:


Mishal: one of the topics w/ Core Team has been wanting to get documentation for standard libraries available on the swift.org website. One of the challengers with DocC today is creating specific/custom URLS - base is flexible, but subpaths are not today.

Mishal: When you gen docs with DocC, you can tell it to use a custom base URL. What happens is when docs are generated, the project name is appended, and prefixed with "documentation". Can't easily drop the "documentation" URL, which is causing issue. JSON, CSS, etc. content is all written to assume that URL structure of "documentation". Don't want to have double layers there.
Want to point directly to subdirectory.
Other challenge that's not as extreme: each website will have it's own custom look and feel. DocC has minimal themeing available. Want to allow to more theming to make it feel consistent with existing pages. Header navigation bar is hard locked.

Joe: There is some theming for header and footer.
Mishal: no hierarchy to provide from top level. Can't jump between different "modules" that are separately created.

Joe: Same issue exhibits with SwiftPackageIndex - jumping between topics. He might provide some useful input for how SPI is working against/with those issues.


Documentation in URL

David: /documentation - workgroup dev is looking into a possibility of this being removed.

Franklin: Removing that part of the URL is an issue we've heard for a while. Docc-render contributors also interested in this. Key question is how to reference/respect tutorials since that's not at /documentation/.

Joe: Action-Item start a thread in the forums about this potential change.

Theming and Styling

David: re themeing and styling, a forum thread would also be good.

Joe: Action item to start this up as a separate thread.

Franklin: Documentation can inject a custom header and footer, TSPL leverages this.

Sophia: option to add a theme
(theme documentation: Documentation)

Daniel: Documentation - documentation for directives - creating custom page layouts directives.

Franklin: allows for providing a bit more "pizazz".

Daniel: Right now it's difficult, and it's sort of weird back and forth, to work out details re: theming and specific desires and outcomes. It might be easier to work on a prototype or example site.

Dave: Have been absent from the website workgroup for a bit, so this was mostly new to me. But suggest a combined meeting might be a much easier way to get details on the table.

Franklin: Agreed, good idea for combined discussion and that if we have something to look at, it's easier to iterate and understand.

Linking between collections

David: linking between separate collections. If they're planning to host everything together, taking the different units and hosting that as a combined archive would be easiest. At least if there's "outer" links aiming to "inner". Bidirectional linking between modules isn't supported yet.

Rauhul: One place (in SwiftPM) is we want to have Package Manager documentation that can be cross-linked.

David: At a first glance, that feels like a single unit.

Rauhul: SwiftPM is a lot more about docummentation - was thinking it might be better broken up, but perhaps not?

David: We've been leaning towards "articles about framework belong in the framework" in terms of units, with some efforts where we'd like to wrapper documentation "linking down" into these articles.

Daniel: Could you expand on bidirectional links?

David: Between modules - or other similar units of documentation. If you have two different modules with articles - one can be "inner" and the other "outer", you can specify one as "underneath" and link to it as you like.
You can also create a top-level wrapper and link down to multiple different modules, but you can't link "up" to the parent module, or "across" between two child modules.
You have to tell docc what other things you intend to link to.

Rauhul: Any reason this can't be more like compiler linker - unresolved symbols that resolve at the end, so that dependencies don't need to be known up front?

David: Main reason we haven't done that is we haven't seen many cases for bidirectional links - but also links can have non-trival effects on the page, changing it's structure, navigation, etc. Definitely doable, but there's some complications there.
The other thing is that it puts more effort on the tool to surface warnings while doing that "build orchestration", opposed to the underlying pieces.

Daniel: There's potentially a middle ground here, leveraging partial builds.

David: That's sound like how we've been thinking about about enabling bi-directional links. That does require that you build them all together.

Joe: Thought there was an index that could be used so that this doesn't rewquire building together.

Daniel: Possible, but better to build together to remove ambiguity of symbols.

David: Outcome is that it's probably best to talk with the team to see how they're hoping to present the documentation to understand and suggestion how DocC can be best used.

Franklin: Can do hard HTTP links
David: But that does make the link a bit more "brittle" - and doesn't bring in title from other article, handling link hierarchies, etc.

(multiple): could potentially make HTTP links into a more thorough reference, but this is a slippery slope that can get out of date. Would need a link, abstract, and perhaps more - but might be able to be provide a means to curate these links into the documentation hierarchy.

Rauhul: is an example of bi-directional links being like referencing in and out of the standard library from the TSPL?

Daniel: Absolutely would be a good use case. Feels like TSPL should sit "above" and link down for the greatest value, but can absolutely see linking back as having value.

David: These do make sense, and the path to enabling this would be building these together in some coordinated manner in order to verify the links maintain consistency.

Rauhul: would love to be involved in documentation & website workgroup meeting. Please cc me for that.

1 Like