search

thegooddocsproject / templates

Templates created by The Good Docs Project - for all your tech writing needs.
https://thegooddocsproject.dev/
Other
677 stars 170 forks source link

Create Docs landing page template or article #251

Open barbaricyawps opened 2 years ago

barbaricyawps commented 2 years ago

Documentation owners might need to think through is how to create a docs landing page for their site. We should create either a template for this or an article with best practices (or both).

Before you begin

  1. Join The Good Docs Project slack workspace.
  2. Read the template contributing process.
  3. You are strongly encouraged to join one of the working groups to get valuable support from the community such as mentorship, Git training, and helpful feedback as you contribute to your first template.
  4. Request access to the templates repository by joining the #templates channel in slack and posting a request.
  5. Assign yourself to an issue for the template that you want to work on.
  6. Add the issue to the templates-kanban and move it into the Research-phase column.
  7. While it is not mandatory to know Git to start contributing, if you are keen, you can familiarize yourself with basic git commands and understand the workflow for contributing on GitHub.
    :information_source: The template leads also provide free hands-on training on Git to the contributors on a need-basis.

Template description

Docs landing pages have the following user stories:

Content type name: Docs landing page

Directory: https://github.com/thegooddocsproject/templates/docs-landing-page/

Tasks

We recommend joining a template working group for support. Join our Slack workspace and ask in the #templates channel how you can find one for your time zone.

To work on this template, you'll want to:

  1. Research examples and identify best practices for docs landing page (see resources below).
  2. Create drafts of the template set deliverables and submit a pull request.
  3. Contact the template leads to let them know that your draft is ready for community review.
  4. Get feedback on the drafts from the community.
  5. After making revisions, update your pull request and let a template lead know.

Helpful resources

Part of what prompted me to open this issue is that I wanted a place to capture resources or notes about docs landing page. There was a great Write the Docs discussion about it. The following are some highlights.

Original post:

Okay Info Architect fans here's a thing I'd love your input on! I keep telling my boss that our docs landing page should be a map to the docs, not an invitation to leave them immediately. docs.mparticle.com

What do you think? Is the landing page above a hot mess or a clever mix of calls to action, tasks, and reference?

One reply:

I feel like what [original post author] is asking for is some feedback about landing page philosophy. What should a landing page do functionally? Should it be a destination in and of itself (and if so, what should users do there)? Or should it be a jumping off point for other docs (and should it direct users to specific docs)? I want to think more about what a docs landing page should do and what the goal of the experience should be from a user perspective. What's the ideal user journey?

My inclination is to bet that, yes, there are probably some general best practices and principles that a good docs landing page should follow. But at the end of the day, what your docs landing page needs to be depends on what your users need it to be. To that end, I suspect the best way to resolve the debate with your boss is with a little bit of user research, if your boss is open to that idea. Even input from as little as 5-10 users could be tremendously informative (in the form of targeted interviews, usability studies, or surveys). Perhaps some Steve Krug books and approaches could be helpful here? (Don't Make Me Think, Rocket Surgery Made Easy, etc.) I would think the end goal would be to identify your core user segments, each segment's needs/journeys, and their expectations coming to the site (which are informed by industry trends and experiences with other docs landing pages for other products). You might also need to figure out which user segment is your primary target (is it new users or experienced users, for example).

Another reply:

The purpose of the homepage is to help triage users to the right information/docs article. It helps to triage your end-users intentions. Finding end-user intention for the homepage is hard and we can do A/B testing to find out after a few experiments. Based of my experience, we have learnt that homepage should have following characteristics:

e.g We use Tidiop chat app and we found that their docs home page is well designed https://help.tidio.com/

A few feedback on your docs home page:

Anita-ihuman commented 2 years ago

Hello @barbaricyawps, I would love to work on this task.