Define a strategy for handling documentation that spans platforms

[jverkoey]

There is a large amount of documentation we need to write as a team that will be pretty similar across platforms.

I see two ways in which we can structure this common documentation:

1. each platform has its own document written specifically for that platform, or
2. one document, with in-line platform switching for code segments.

Choice	Pros	Cons
1.	Content can be written directly for the target audience.	Have to write n times as much copy.
2.	Less content to write.	May be more difficult to discuss platform-specific nuances.

I think that we can do 2. by tagging platform-specific content in such a way that our website can filter out irrelevant content. E.g. there might be a platform picker that shows all elements tagged with that platform. This is similar to how the Milemarker website is designed. It's simple and works decently well.

[pingpongboss]

I heavily favor #2 though it's more technically challenging. Another con of #2 is how do we embed this document in each platform-specific repo?

On Mon, Nov 7, 2016 at 12:47 PM featherless [email protected] wrote:

There is a large amount of documentation we need to write as a team that will be pretty similar across platforms.

I see two ways in which we can structure this common documentation:

1. each platform has its own document written specifically for that platform, or
2. one document, with in-line platform switching for code segments.

Choice Pros Cons

1. Content can be written directly for the target audience. Have to write n times as much copy.
2. Less content to write. May be more difficult to discuss platform-specific nuances.

I think that we can do 2. by tagging platform-specific content in such a way that our website can filter out irrelevant content. E.g. there might be a platform picker that shows all elements tagged with that platform. This is similar to how the Milemarker website is designed. It's simple and works decently well.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/material-motion/material-motion/issues/13, or mute the thread https://github.com/notifications/unsubscribe-auth/AAr8KkW-7O8Zn4myP9IWjarjFX0CVliOks5q72QYgaJpZM4Krggd .