Website Project Plan (2019)

--- title: Website Project Plan (2019) tags: website --- # Website Project Plan (2019) ## Target Users ### Design system author This author documents the various design primitives that drive component and experience creation. #### Site related jobs 1. Defining/documenting Fluid principles like mobile-born, coherent, inclusive, intelligent etc 2. Documenting color ramps, color groups, elevation, typography, motion and iconography 3. Documenting localization, accessibility basics, voice & tone etc 4. Defining experiences like notifications, user engagement, error & recovery etc ### Spec writer The spec writer is the person who defines and documents the requirements for a new component in Fluent. They will spend a great deal of time writing the initial documentation, but will also be involved in updated the docs over time. #### Site related jobs 1. Linking to or documenting redlines (colors, sizes, layout) 3. Documenting accessibility requirements for a control 4. Linking to or documenting interaction model for a control 5. Writing overview and documenting correct component usage 6. Documenting guidance for the internationalization of a control ### Component implementer The implementer is the developer who takes the control spec and implements that control in a given language/platform. #### Site related jobs 1. Reading Spec docs and creating a control that faithfully implements those specs 2. Writing code examples to demonstrate to dev consumers how the control works 3. Documenting accessiblity features performed by the control, and highlighting work still required for them to be fully accessible ### Design consumer The design consumer creates new experiences using the defined design system and controls. They need to know what controls are available and how to use them. #### Site related jobs 1. Searching for icons, colors, typography and other design primitives and how to use them 2. Searching for controls available on their platform 3. Learning how controls can be combined and/or customized to create new experiences 4. Determining necessary information to be passed on to developer in order to create an accessible experience ### Dev consumer Given an application design, the dev consumer needs to determine which controls to use, and what they must do to integrate or customize those controls properly. #### Site related jobs 1. Finding the correct control to use based on design 2. Determining how controls can be customized to meet design requirements 3. Understanding what accessibility tasks are done for them, and which ones are required from them. ### Other Jobs #### Bug submitter When submitting a bug against an implemented control, the bug submitter needs to know if the bug is in the control itself, or in the spec. If the control is properly implementing the spec (in color, or functionality etc) then the bug needs to be raised with the designer. ## Problems ### Customer Facing 1. Component specs and consumer documentation are currently co-located making it hard to serve diverse audience properly. 1. The SEO for our current documentation is incredibly low. 1. We have no analytics to measure traffic 1. The entire app loads to display a single page 1. Site has a history of downtime ### Author Facing 1. Dev knowledge and setup required to make content changes 2. Markdown format is not well understood by content authors 3. Preview of authored content requires a 30+ minute build of entire project ### Developer Facing 1. The website project's inner loop is hard to develop on 1. Building the website takes too long 1. Content and presentation are coupled together 1. Scaffolding new sites with example-app-base has a steep learning curve, minimal docs and support 1. Layout and content model changes require heavy dev knowledge and large amounts of time 1. Current public site requires all of the content to be in the OUFR repo, 1. Reusing existing content (like our internal HIG) is very difficult to do 3. Significant time wasted debugging and mitigating issues caused by website host CSS. ## Goals Create a modern documentation platform that enables Fluent and partner teams to create and document React based UI controls. We'll measure our success in these ways: 1. Reduction of build time by 50% 3. Onboard 3 additional teams to our Gatsby theme and consume existing Fluent docs 5. Enable content contribution from at least 5 designers 6. Improve SEO to place new controls in top 5 for both flunt ui + component and ui fabric + component ### Stretch Goal Create a format which allows partner teams to publish information about their available controls which can be consumed and published on the Fluent website (public or internal) ## Plan The plan is to create a Gatsby theme that will replace `@uifabric/example-app-base`. Gatsby themes will make it easy to consume, extend, and override portions of the site to fit a user's needs. ## Steps ### Fluent Design Docs Stream 1. 1. Set up docs repo for Fluent team 2. Create NetlifyCMS data data types to match their page needs ### Website building stream 1. Determine page structure for developer documentation (wireframe output) 1. Build component example display 1. Building Plugins 2. Support consuming components outside of Fluent repo ## Key Dates ### End of October #### Tasks - Work with Fluent design team to determine navigation/content hierarchy of future site - Determine data model for their design documenation - Create repo for designers to start creating content - Wireframe of component page - Deploy Gatsby site to display new component documentation/examples #### Demo How this modern stack improves dev workflow. Design wireframe for new producer spec pages ### End of November #### Tasks - Beta of Gatsby theme ready for customer preview - Prototype of doc format that supports importing of customer components into directory - Design team will be regularly committing document #### Demo How Gatsby theme allows other teams to scaffold and customize new public docs site. How storybook can be extended to improve developer productivity. Report on design success in conributing docs. ### End of Quarter (early January) - 1.0 launch of gatsby-theme-fluentui-docs - Beta of doc format for ingesting partner controls - Design has finished content migration for all producer docs **Demo:** ? ## Potential Development Partners docs.msft (Robert Outlaw, Joe Friend) Teams (David Zukowski) BAG (Adam Sivins) ## Potential Consumer Partners [OneDrive Items View](https://odsp-int.azurewebsites.net/items-view/) Teams internal packages (chat/calendar etc) [WAC/ribbon](https://wacribbon.azurewebsites.net/) CSEO M365 Admin [BAG](https://baguiguide.azurewebsites.net/) React Native (Adam) ## Related resources [Website Plan Details](/dhu4RmfpTJCuVANgbng9_g)