search

writethedocs / www

The main website for Write the Docs.
http://www.writethedocs.org
Other
1.31k stars 504 forks source link

Documentation Guide V2 #527

Open Bradamant3 opened 6 years ago

Bradamant3 commented 6 years ago

Note: A big update is below in the first comment

Notes toward a new organization for the Guide:

New to caring about docs? Start here!

Seasoned docs veteran? Explore from here!

For everyone

Notes: when we've got the new IA in place, can we put the guide back in the left nav? And can we do one of the following:

ericholscher commented 5 years ago

Going to follow up here with some thoughts on a v2 of the guide, which is a bit more all-encompassing than the previous vision.

Backstory

Historically, we've had a bunch of good guide content, then other stuff scattered around the site. This includes newsletter writeups on various topics, talk videos, unconference notes, and lots of other good content. We have a problem that very little of this content is discoverable, and there is lots more we should be writing in the guide itself.

To start to solve this problem, @bethaitman created the Newsletter index (http://www.writethedocs.org/newsletter/#index-of-newsletter-topics) -- this takes all of the content in the newsletter and puts it into topic-based categories to make it much easier to find. It also takes the content from being published in a "May 2018 newsletter" which nobody will ever look at again, and makes it much more discoverable.

Future

My current thought here is to take the newsletter index concept, and apply it to all of our Write the Docs content. We would create a new global index, and have a series of various "content types" that we can put under each topic heading. We currently have a number of content types, and could include more:

The goal here would be to re-purpose our existing newsletter index, talk archives, and guides into a much more user-friendly and discoverable community resource.

A lot of this is inspired by @evildmp's work on Django's documentation and talks at our conferences. More info here: https://www.divio.com/blog/author/daniele-procida/ -- though I wish I could link to the "Documentation Structure" section of our v2 guide with this link, and his talk, already in it :)

Deployment

The goal here is to be able to iterate and make it better over time. We could start with simply promoting the newsletter index to the top-level. We can then slowly over time add all our existing content into the guide. This could include GitHub issues like "index all podcast episodes" or "index the talks from the 2019 portland conference". Beth has started to index a lot of the conference talks, so that should be pretty simple to add.

The goal here is to slowly iterate and come up with a structure that makes sense. I imagine we'll have to change the IA of the index once or twice, as we figure out what all we really want it to do. We do want to make sure we aren't blocking on a huge refactor, but instead slowly adding value over time as we have time to add things to the index and write new content that is missing.

Benefits

People would be able to learn about the topic that they care about, in the format that they want. Some people love deep dives from a conference talk, and others wants just a quick high-level overview to familiarize themselves with the topic. Being able to provide resources to our community in a number of formats lets us teach people where they are. It also brings all the various work that WTD (and folks outside our community) are doing in a topic-based fashion.

plaindocs commented 5 years ago

I see these two approaches working well together. With a "topic/tag" based approach that Eric mentions, we should (with some significant hand-waving) be able to assemble series for devs (a, b, d), new writers, b, d, e, f) etc.

camerons commented 5 years ago

A dozen or so of us tech writers are committed to creating a "best practices" guide and associated suite of templates for creating technical documentation for Open Source Software projects. It started as a Google Season of Docs idea, and has since grown beyond the scope of SeasonOfDocs, into what we are tentatively calling TheGoodDocsProject.

I'd suggest that our vision and that of the WriteTheDocs Guide are very closely aligned. We could tak on the responsibility for a few sections within your WriteTheDocs Guide v2.

Ideas being developed so far:

bethaitman commented 5 years ago

I really like the idea of a global index that we can start slotting more and more content into - both making what we have already more discoverable, and bringing in new content (even encouraging it, when it's clear there's a gap to be filled).

I've said this before but I think it's crucial to start with a reasonably strong IA that matches up well to what our audience is looking for - agree that it can evolve over time, though.

I'd love to see the pages for each topic evolve into less of an index and more of a true 'landing page' for that topic - ie not just a list of links, but something that provides a meaningful introduction to give context to those links to other resources.

Re: The Good Docs Project, these approaches definitely seem compatible. I guess if we can start coming up with a draft information architecture for the guide, it'll be easier to see where the sensible overlaps/areas for collaboration are

ericholscher commented 4 years ago

@bethaitman This is a lovely example of something we could build once we have all the tagging data put together: https://gist.github.com/scottydocs/c956c5328bca8e10cc8df9e3406104d7