Documentation TF

[jccr]

Overview

Problem statement

Write, publish and maintain documentation to help the community find helpful and practical information on EPUBs.

Inspiration from: https://github.com/w3c/publ-cg/issues/88

EPUBs are complicated. The spec doesn't fit on an index card. There are more reading systems then Democratic candidates for President. Book content is infinitely varied.

Proposed work

• Contribute to MDN and Open Web Docs
• Submit technical writing on EPUB tutorials, guides, "just the basics", and best practices.
  • IBM (the exceptional technical writers that they are) had an EPUB tutorial published in 2008!
• Replicate the knowledge-base and reference guide style of documentation that's published in the DAISY Accessible Publishing Knowledge Base.
  • Hub for practical techniques and examples
  • For example the doc on page lists is very handy.
• API documentation on related and specific HTML/CSS/JS web tech such as the epubReadingSystem object and other RS concerns.
• Triage docs based on the 33 open issues tagged as "Best Practice" and 4 other "Question" & "Accessibility" issues in the prior github repo (publ-cg)
• Attempt to get compatibility tables going, a la caniuse.com

Dependencies & risks

Stakeholders

• MDN Editorial Team
  • Follow strict editorial guidelines
  • Stay away from how EPUB overlaps with HTML
  • Offer specification interpretations
• EPUB WG
• EPUB CG
• W3C Product Advisory board
• Large community of developers
• Large community of non-developers

Risks

• Volunteers
  • Technical writing skills
• Resources
  • Time, effort, coordination
• Review and editing process
  • Quality control
  • Tracking mistakes / errata
• Upkeep and maintenance
  • Documentation going stale or out of date
• Vast ocean of RS implementations out there!
  • Compatibility data

Success criteria

• Users within the EPUB ecosystem have something better than relying on Google searches.
• SEO for EPUB help and guidance terms benefits from this work.
• Collaboration and maintenance on docs is easily done with little friction.
• The community feels alive again and this effort could cascades into and stimulate activity on StackOverflow and other forums.

[ghost]

Great! Thanks @jccr for leading this new TF. Let's talk about it in today's call.

[jccr]

Open call for volunteers!

So far I've identified:

• @jccr (myself), TF lead & contributor
• @larscwallin, contributor
• @TzviyaSiegman, advisor & liaison
• @GeorgeKerscher, reviewer

If you see yourself on the list, feel free to acknowledge so 👍
(and if I got you down incorrectly feel free to correct me)

[jccr]

https://github.com/w3c/epub-specs/issues/1507 This issue will be a planned for action by this TF

[Jeffxz]

Hi @jccr how was documentation TF coming along? If anything I could help with please let me know.

[Jeffxz]

Just heard from epub wg that @dlazin will be able to take this. Would you be able to share the progress in CG meeting next Wed @dlazin?

[dlazin]

Yes, I would be happy to share on Wednesday.

In short, late last year @TzviyaSiegman and others connected me with folks at MDN; at their request I put together a checklist explaining the proposal, and MDN got back to me today to say that it's approved.

I have a VERY small amount of WIP documentation in my fork of mdn/content, and you can see what I'm thinking of as the minimum-viable set of launchable docs by looking at the nav structure I put together.

I haven't touched this in a few months — short on time like everyone else — but I would really like to see it get done, so let's work together!

[iherman]

The issue was discussed in a meeting on 2022-03-03

• no resolutions were taken

View the transcript

### 4. Accessibility of image-dominated FXL publications (issue epub-specs#2012) _See github issue [epub-specs#2012](https://github.com/w3c/epub-specs/issues/2012)._ **Shinya Takami (高見真也):** FL a11y issue was raised (see issue). … MURATA, what do you think?. **Murata Makoto:** I do not understand the practical implications. **Shinya Takami (高見真也):** (Japanese). **Murata Makoto:** Informational document (Japanese). … DAISY (Japanese). **Shinya Takami (高見真也):** (Japanese). **Murata Makoto:** Yes. … Will this have any impact on 3.3?. **Wendy Reid:** No. … These are not published, and would only be WG notes, neither on REC track. … We can add something about image dominated publications (or add more). … We have been trying to avoid discussing a single content type, but we can attempt to differentiate between mainly image FL and text based FL. **Murata Makoto:** I would like to make this more obvious - Image based FL content is not accessible. Period.. **Wendy Reid:** We wouldn't really put this into core anyway, it would be part of a11y if we did add it. … There are a lot of problems, and we really can't standardize yet. **Dave Cramer:** Looks like we have a path forward. … AOB. **Dan Lazin:** I heard back from MDN today, they have approved our proposals to add publishing related content at MDN. … Now we just have to write the docs. > *Dan Lazin:* See ["Web-related technologies" on MDN](https://developer.mozilla.org/en-US/docs/Related). **Dan Lazin:** We have an outline for minimum viable, but not time to actually do it now. > *Dan Lazin:* See [first outline](https://github.com/dlazin/mdn-yari/blob/main/kumascript/macros/EPUBRef.ejs). **Dan Lazin:** but we do have an outline if anyone wants to help. **Zheng Xu (徐征):** In the CG we have a taskforce for MDN, can we assign it to you?. **Dan Lazin:** Yes, I knew it existed and the TF connected me to the MDN people. **Zheng Xu (徐征):** I will add you to the CG issue. **Dan Lazin:** I do have the previous drafts. > *Zheng Xu (徐征):* here is the CG issue. _See github issue [publishingcg#10](https://github.com/w3c/publishingcg/issues/10)._ **Dave Cramer:** The MDN format is weird. ---

[Jeffxz]

That's great! Thank you @dlazin. Look forward to next week meeting