Orienting Readers in iTwin.js Documentation

[ben-polinsky]

There are a number of issues with iTwin.js documentation. Most of these fall under the scope of "it's tough to find what I need". This encompasses a poor search experience, design issues, navigation, and missing guided documentation. It's tough to get an idea of what the library can do.

We have some getting started guides for a few specific use cases, after which we offer a couple of suggestions of where to go next. There's no logical sequence or hierarchy that users can follow.

Many developers have done a great job of adding documentation and we consider it necessary to complete pull requests, but too often these additions exist as a singular document or documents in isolation because we don't have good organization. Generally, within topics, there is no natural flow from one sub topic to another.

BIS has gone to great lengths to try to orient the reader and have continuity between sections. There's great graphics and geometry knowledge (I'm sure other areas, too). We just need to mold and shape everything a bit.

Before we tackle the design of the site, the search experience, etc... we need to get a grip on how we structure and organize learning documentation for different features of iTwin.js. Work has started and stopped over the past two years, but I know some good thought has been put in by colleagues @michelledillard @ColinKerr @aruniverse @calebmshafer and others.

What I am proposing is to document a hierarchy of our documentation - not for each and every doc - but into general subject areas. Currently, (even for learning docs) most categorization is by package (frontend, backend, common) - but there's really no rhyme or reason to the structure otherwise: some documents happen to be indexes to related material, some are one-offs. Once this hierarchy is in place, I think it's important to have gentle introductions to getting started with each area of functionality. These are sorely needed. Everything else kind of naturally flows from there.

This also relates to:

• needed content
• outdated content
• search
• navigation
• how a page is structured/designed
• how docs are structured - guides vs learning docs
• LLM digestion

[michelledillard]

@ben-polinsky I have a proposed organization we put together some time ago when there was some focus on Information Architecture. I'll track that down and post it here for input. Additionally, there has been some conversation regarding a content working group.

I share the same concerns as you outline here along with the open question of aligning iTwin.js, iTwin platform, and as we continue to combine Cesium into a comprehensive platform solution, that needs to be considered.

@shehzan10 There have been various discussion around a working group for these topics. Maybe we should consider kicking something like this off in Q2?

[ben-polinsky]

@ben-polinsky I have a proposed organization we put together some time ago when there was some focus on Information Architecture. I'll track that down and post it here for input.

Thanks - would be very helpful. I didn't get to post my proposal on Friday - still futzing over it.

[shehzan10]

@shehzan10 There have been various discussion around a working group for these topics. Maybe we should consider kicking something like this off in Q2?

@michelledillard Feel free to propose as part of the planning. We should all strive to lower the barrier to entry on all fronts.

[michelledillard]

@ben-polinsky I'm still looking for the IA we previously created. New computer and all my links and docs got scrambled. Wanted to provide an update, so you didn't think I forgot.