Page MenuHomePhabricator

Research past strategies and ideas for dividing, grouping, and assessing technical docs
Closed, ResolvedPublic


The following resources contain information and ideas about approaching our technical content and assessing it. They also contain a TON of other info. To keep this project in scope, do not get distracted by all the content in these resources that is about what our docs lack, or what developers want from the docs themselves. Focus on these three questions:

  • What strategies or tools have people used, considered or suggested to identify sets of related docs or divide up the content space?
  • What strategies or tools have people used, considered or suggested to assess the state of a set of related docs, and identify work needed to improve them?

To review:

Event Timeline

TBurmeister changed the task status from Open to In Progress.Aug 9 2022, 6:09 PM
TBurmeister triaged this task as Medium priority.

Note to self: some good thoughts about doc metadata vs. templates here, i.e. "Status would be one example of information that should be first-class metadata, and not a labyrinth of templates."

A choice tidbit from T156301:

I would be interested in trying to help run a pilot project with Labs and Tool-Labs where we know that we have a lack of tutorial content and some specific asks from the past Tool Labs user surveys that we could try to organize around.

I think this is exactly the kind of thing it would be effective to organize around.

The vision I've kind of have in my mind is this: After some outreach, we'll have a group of people interested specifically in writing documentation. Instead of sending them to Easy Doc Bugs, which is intimidating and hard to parse, let's connect them directly with people, projects, and mentors who can provide guidance on what to work on.

I attended the summit session Better recommending of tasks suitable for new technical contributors (T149564), and the thing that stayed with me is that it's the connections with people that encourages new contributors.

My research, conclusions / recommendations, and related artifacts from Q1 are at These are my thoughts only -- KBach and I still need to compare our findings, reconcile and disagreements, and create a shorter executive summary.