[HarfBuzz] Documentation-requirements gathering

[Nathan Willis]

Hi everybody,

As was alluded to on the list / issue tracker several months ago, I am the
contractor who is going to be working on HarfBuzz documentation as part of
the project's MOSS grant from Mozilla.

(It was a while ago; to be honest we were caught a little off guard by how
quickly the proposal was approved, and had to schedule it accordingly)

We have a fairly concrete roadmap established for the high-level pieces of
documentation that this effort is going to involve. The most critical
things are likely to be guides for new users of the library on different
systems and coverage of the external APIs. Flowing out of that, of course,
there is more: there are certainly internal pieces that need reference
documenting as well.

Behdad and I talked last week and, as many of you know, most users of the
library struggle with OpenType shaping (the need for it and the process) in
general. Making all of that clear, and how HarfBuzz accomplishes it, is the
goal here.

With that in mind, I definitely want to start out by asking the developer
and user community to weigh in with its concerns and its wishlist for what
you think is most useful. Obviously we can't supply an infinite amount of
documentation, but I thought it'd be smart to begin with an open call for
what *your* personal requirements and perceived needs are, to make sure
we're on the same page and looking in the same direction.

So please consider this an open call for input. I'd like to hear from you
regarding:

- If there is anything in particular about the codebase that you think
needs attention
- If there are things best avoided
- If you are a HarfBuzz user who has encountered specific trouble where
additional documentation would have helped
- If you are only casually using HarfBuzz but the shaping and layout issues
have been a stumbling block in the past, what material would have helped

Also, one clarification: I am open to hearing discussion of implementation
details, if you care strongly about them (such as where the documentation
lives in the tree or how it is organized). But, that said, my primary task
on this project is to create the words themselves, not to spend time on CSS
theming or solving markup-language conflicts. We do want the doc corpus to
live alongside the codebase and be maintainable long-term, but that starts
with getting the words there first.

But enough from me; please speak up if this interests you.

Thanks,
Nate
-- 
nathan.p.willis
nwillis at glyphography.com <http://identi.ca/n8>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.freedesktop.org/archives/harfbuzz/attachments/20180716/a0bc7c4e/attachment.html>