product-management
product-management copied to clipboard
hackforla
Create a document template for Guides
Overview
We need to create a document template for guides so all guides are standardized.
Action Items
- [x] Use the kanban board guide as the example hackforla/knowledgebase-content#16
- [x] Create a document template for the guide
Resources/Instructions
Google drive for new document Guide draft Template for Creating a Guide (referenced in the guide to making a guide)
@Olivia-Chiong is the end user for this the Product Management team (to document internal policies) or is this for other teams/uses as well? I'm expecting the use case is internal documentation, and is not intended to be used for new feature documentation.
@mariastudnicka created a very nice design for this guide and I am told we can make it into a template.
@rmcrowell This is for PM team and we are also sharing it on the website for external. I think you've made a lot of good progress. Do you think it's ready for review?
@rmcrowell sorry for the delay in getting back to you
Formatting Issues: See slack guide for examples of how it should look
- [ ] First Page
- [ ] Logo is too far to the top (check the margins)
- [ ] Title format is not centered (left to right) and too high up on the page
- [ ] (2nd page onward) header
- [ ] the logo is missing
- [ ] the text is too far to the right
Examples:
- [ ] Please use examples everywhere. There are some people who will not know what you are talking about unless they can see it in action. We could provide links to other documents, but it's easier for the reader, if we just put the example in line.
- [ ] Use outlines to draw attention in screenshots (review the other guides and determine if we have a color we prefer and then specify that particular color be used. For instance the orange in this screenshot below is #ff832e
- [ ] Use arrows where outlines don't work (I think this arrow should be the same orange as above though
Who its for: These guides are for use by anyone who is facing the same issues. Here is my wording for Civic Tech Structure that will help you understand the mission and purpose:
The Civic Tech Structure project seeks to improve existing structures and create new ones that make it easier to share replicable processes and practices so that the civic tech community can iterate on each other’s work, improving outcomes for the whole ecosystem.
Our Civic Tech Structure project is responsible for publishing all of our guides and other reference materials that we hope will help other people and organizations to stand on the shoulders of those who contributed before them.
I'm making these updates. I'm delayed right now because I just figured out how to insert clear drawings into the document, and will add steps to explain that as well. (linked image is the difference between the unedited image, the Google drawing embedded directly into the document, and the clearer image after a few steps.) It's possible but will take a bit of time to redo the images and document how to do it.
This document is updated and ready for review.
Document can be found at https://docs.google.com/document/d/1-8gmeC-wnfM8C8fVvmTP1BLA2WfNjKH_XJrHB1OAV6Q/edit?usp=sharing
@ktjnyc is going to take a look to see if the template encompases everything she would have needed if there was a template before she started.
@Olivia-Chiong we should assign anyone who is done with a guide draft now, to review this template and see if same as above.
@erigilg Since you made the tracker for the guides, can you review this template Rose has come up with and provide any suggestions/comments? Thanks!
I left a few comments in the document as well, but some general feedback:
- It would have been good when I was creating the guide to know what sections I needed to address (we could standardize to include What/When to Use/Why/FAQs/Glossary of terms/Other Sections)
- It would have been good to have had a shell document with all the styling available to create the copy from
- Some guides have table of contents and some do not - we should make a decision if we want that to allow users to skip to certain sections or not and make standard across the guides
- Potentially include a section on what to do when you are done with the guide - i know the issues tell you to add/remove tags and such but i found that i assigned a bunch of people and after a week didn't get feedback. Then i slacked it to the PM channel and got a few more reviews but we should set a standard for how long to leave it in peer review, how many reviews minimum should be conducted.
- Style wise it was suggested that bullets work better than long paragraphs, we could add some guidance to a helpful formatting section that covers bullets, use of screenshots, outlining the screenshots, etc.
Added my comments to the doc but in general:
- It would be clearer if the beginning of the guide for guides included the purpose of guides and in this case what this specific guide is for.
- Agree with Katie on adding sections based on other great guides that have been made.
- It would be helpful to have a general overview of what steps should be taken when making a guide and then deep dive into the guide's sections.
- I would suggest making a template that's referenced inside the guide. It is relatively easy to make a template in google docs to maintain same look and feel in all guides. Here's a guide from google on how to make templates.
@tan-zhou and @daniellex0 this is the guide/template for creating guides. It's a WIP, but would love to have your input. Thanks!
The guide needs to be updated to say that if there is a long url and a name for a thing it needs to be clean. So for instance this:
Should look like this
Header should be formatted in such a way that people writing guides can create them. See the template that the UX team is creating: https://github.com/hackforla/UI-UX/issues/55
Here is the one appearing in our guide:
Here is an example of one appearing in another guide
