Skip to content
This repository has been archived by the owner on Sep 24, 2022. It is now read-only.

about how-to probably shouldn't suggest layout be in a table #105

Closed
camerons opened this issue Feb 9, 2020 · 1 comment · Fixed by #108
Closed

about how-to probably shouldn't suggest layout be in a table #105

camerons opened this issue Feb 9, 2020 · 1 comment · Fixed by #108
Labels
decision For issues that require TGD committee consensus on prior to implementing template-about-howto

Comments

@camerons
Copy link
Member

camerons commented Feb 9, 2020

Re: https://github.com/thegooddocsproject/templates/blob/master/how-to/about-howto.md

When you are explaining steps in a process, it can often be useful to include a screenshot for each part of the process. What can often happen is that when you try to insert a graphic or screenshot into the flow of the procedure, it breaks the procedural content up and makes the instructions difficult to read.
In the template-howto.adoc file, you'll notice the tabular step format in the Step-by-step section of the template. The tabular format allows you to add in your procedural steps right next to the screenshot and reference steps with call-outs.
If you procedural steps do not require screenshots, then you can default to an ordered list. You can also get this structure in Markdown, but you may need to resort to HTML tables. For Markdown, keep the list as an Ordered list.

Note: Google's developer documentation style guide advice is:

Laying out images on a page
Don't try to place an image manually; for example, don't use a style attribute or other workarounds to control the image's left/right justification or the margins around the image.

I feel we shouldn't be recommending the use of tables to address image alignment. My reasons:

  • Responsive web design principles suggest that we shouldn't assume the target screen size, and using tables locks us into a specific screen size.
  • Applying layout recommendations contradicts the Google's style guide that we have decided to follow.
  • TheGoodDocs templates should focus should be on content rather than style (although we might cover style elsewhere).

Note: I do think the use of tables for presenting images next to instructions is a good idea, but I think there are other ways to do it too, which should be considered as well.

@camerons camerons added decision For issues that require TGD committee consensus on prior to implementing template-about-howto labels Feb 9, 2020
@camerons
Copy link
Member Author

Jared confirmed he was ok with the suggestion on email.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
decision For issues that require TGD committee consensus on prior to implementing template-about-howto
Projects
None yet
1 participant