New structure for the guide

bethaitman commented 4 years ago

This is a proposal for a new way of organising all the content we have on the site: talks, guide entries, newsletter articles, and anything else that comes up. We'll never get this perfectly right, but I'd like to get a reasonably flexible structure that can cope with change and expansion.

I've tried to make it as task-based as possible, in the hope that this will map up to things that people are looking for, but I've not been able to do it totally.

All the headings are temporary: I don't think I have the names right yet.

Micro-level writing: This means the nitty-gritty of writing, and includes things like:
- grammar
- plain english
- very specific writing questions (one word vs another, using abbreviations, etc)
- storytelling?
- code samples?
- other media - videos, diagrams, screenshots?
Page writing: Writing at a higher level, roughly thinking about a "page". Includes things like:
- task-based writing
- specific doc types (how-tos, reference/API docs, tutorials, etc) and how to write them
Doc set writing: Working at the level of thinking about a whole (or part of) a set of docs. Includes things like:
- information architecture
- refactoring and restructuring (legacy) docs
- maintenance
Jobs and careers
- hiring
- getting hired
- related roles
- career growth
Design and UX
- accessiblity
- design
- UI writing
Doc sites and tools
- docs-as-code
- site design, metadata
- DITA
- automation and automated testing
- Git
- markdown and other formats
Analytics and metrics
- user research
- gathering and acting on user feedback
- measuring docs success
- metrics
Interpersonal stuff. I think this label doesn't actually work - it won't be what people are looking for
- building a docs culture
- building a community
- working with writers (review, editing, teaching)
- customer support, working with support
- helping engineers to write
- working with other roles (product managers, higher-ups, etc)
Planning
- prioiritisation
- agile workflows
- strategy
- defining success

bethaitman commented 4 years ago

Relevant links:

plaindocs commented 4 years ago

What about Interpersonal Stuff -> Culture & Community

bethaitman commented 4 years ago

Notes from the conversation:

cross-linking is important: for example, 'defining success' under planning
interpersonal bucket: can break it down at least in one part to working across roles, and the other as culture and community. Note that there's a big difference between internal and external community building, though tactics can be similar. Meetups can go inside culture+community.
missing topic: docs migration
tension between 'doc set writing' and 'doc sites and tools'
'doc set writing' - not writing, more management, stewardship. What should we call this? Essentially it's library science. Is this about concepts?
Divide in docs-as-code between philosophy and tools/stuff to get it done
Perhaps tools can be its own thing, doc site design goes under docs and ux, and everything else goes under doc site writing.
storytelling move from micro to page-level
new name for micro-levels - specifics, details, low-levels. The mechanics of it.
missing: principles, or rather good practices

ericholscher commented 4 years ago

In terms of implementation, I think we could start with adding the tags into a Sphinx RST index directive.

It would look like:

.. index::
    community-building
    best-practices

That will then end up in the generated index, and we can also output it on the main page.

ericholscher commented 4 years ago

We should also keep this in step with #527

bethaitman commented 4 years ago

Items to use for testing the Sphinx index:

Jobs, subcategory Hiring:
Jobs, subcategory career growth
- https://www.writethedocs.org/newsletter/#career-growth
- http://www.writethedocs.org/videos/na/2016/we-re-not-in-kansas-anymore-how-to-find-courage-while-following-the-technical-doc-road-christy-lutz/
- https://podcast.writethedocs.org/2019/03/31/episode-21-career-growth-leadership-mentoring-technical-writing/ - this is an external link, worth testing to see if we can deal with these
Analytics / metrics
- https://www.writethedocs.org/newsletter/#metrics
- http://www.writethedocs.org/videos/prague/2018/measuring-the-impact-of-your-documentation-liam-keegan/

bethaitman commented 4 years ago

Updated categories proposal, based on discussion above. I'm still not in love with the sentence/page/doc-set level writing distinctions, but I think they'll do.

sentence-level-writing
- grammar
- plain-english
- specific-writing-questions (one word vs another, using abbreviations, etc)
- code samples
- other-media (videos, diagrams, screenshots - could be their own sub-categories)
page-level-writing (writing at a higher level, roughly thinking about a "page")
- task-based-writing
- specific-doc-types (how-tos, reference/API docs, tutorials - could be their own sub-categories)
- storytelling
doc-set-writing (Working at the level of thinking about a whole - or part of - a set of docs)
- information-architecture
- refactoring-and-restructuring
- legacy-docs
- maintenance
jobs-and-careers
- hiring
- getting-hired
- related-roles
- career-growth
design-and-ux
- accessiblity
- design
- ux-writing
- doc-site-design
doc-tools
- docs-as-code
- DITA
- automation / automated-testing
- git
- markdown and other-formats (?)
- doc-migration
metrics-and-analytics
- user-research
- user-feedback (gathering and acting on)
- measuring-docs-success
- metrics
culture-and-community
- building-docs-culture
- building-community
- meetups
working-across-roles
- working-with-writers (review, editing, teaching)
- customer-support, working-with-support
- helping-engineers-to-write
- working-with-other-roles (product managers, higher-ups, etc)
planning
- prioritisation
- agile-workflows
- strategy
- defining-success
philosophy (this is a bit of a nebulous category but I think some important stuff fits in here. It won't come up much anyway)
- docs-as-code
- best-practices

djwfyi commented 4 years ago

Johnny-come-lately, but here's my take on the categories, with some additions I thought were missing:

Writing
- words
  - grammar
  - plain-english
  - specific-writing-questions (one word vs another, using abbreviations, etc)
  - code samples
  - other-media (videos, diagrams, screenshots - could be their own sub-categories)
- topics (writing at a higher level, roughly thinking about a "page")
  - task-based-writing
  - specific-doc-types (how-tos, reference/API docs, tutorials - could be their own sub-categories)
  - storytelling
- docs (Working at the level of thinking about a whole - or part of - a set of docs)
  - content-strategy
  - refactoring-and-restructuring
  - legacy-docs
  - maintenance
Career-and-Community
- jobs-and-careers
  - hiring
  - getting-hired
  - related-roles
  - career-growth
- connecting-to-other-tech-writers
  - building-docs-culture
  - building-community
  - meetups
  - Slack
- working-across-roles
  - working-with-writers (review, editing, teaching)
  - customer-support, working-with-support
  - helping-engineers-to-write
  - working-with-other-roles (product managers, higher-ups, etc)
- professional-development
  - books
  - courses
  - conferences
  - newsletter
Theories
- Information-Architecture
- design-and-ux
  - accessiblity
  - design
  - ux-writing
  - doc-site-design
- docs-as-code
- best-practices
Tools-and-Toolchains
- doc-tools
  - structured-writing (DITA, docbook)
  - automation / automated-testing
  - version-control (e.g. git)
  - markup-languages (Markdown, rST)
  - doc-migration
- Style-guides
  - Google
  - Microsoft
  - Best-practices
- software
  - CMS (Flare, Paligo)
  - HAT (Framemaker, RoboHelp)
  - Video (Camtasia)
  - Screen-capture (SnagIt, Capture)
  - Image-processing (Photoshop, GIMP)
  - Static-Site-Generators (Jekyll, Hugo, Sphinx)
  - Knowledge-management (Confluence, Guru, Salesforce Knowledge)
- metrics-and-analytics
  - user-research
  - user-feedback (gathering and acting on)
  - measuring-docs-success
  - metrics
- planning
  - prioritisation
  - agile-workflows
  - strategy
  - defining-success

bethaitman commented 4 years ago

Thanks @dwhitelf! I've had a go at putting the actual index together, and stole a few of your ideas - I liked how you phrased the writing topics, and I'd missed out style guides, which you added back in.

I'll revisit again once we publish the index, when it'll be a bit easier to work this out, as we'll have a real-life example to compare against. I'd like to keep it to two levels if I can, though, rather than the three levels of nesting you've got.

writethedocs / www

New structure for the guide #1085