Introduce an open Documentation policy

I think the project would benefit from having an open policy on getting documentation or Guides added or amended, similar to what the Rails team implemented five years ago.

The current process of submitting documentation via pull requests the the Ember Website repo takes too long, requires too much effort on the part of the documenter to chase up someone on the core team to get the PR accepted or any kind of feedback.

The danger is that documentation could be submitted that has errors or is factually incorrect or inconsistent, but perhaps itā€™s better to have documentation that is 60% correct, say, than non-existant?

Anyway, the rails-doc project saw some good uplift after implementing their curent policy so I thought it would be worth starting the discussion.

2 Likes

This is a good idea. I canā€™t promise that weā€™ll implement it, but it certainly merits further discussion.

1 Like

I would be very much in favour of a project like this. I think it has several key benefits:

  • Reduces the barrier to contribution
  • Frees up the Core Team
  • Allows documentation ā€˜championsā€™ to evolve organically
  • Guards against stale information (i.e. more likely to be kept up-to-date)
  • Encourages contribution at the point of inaccuracy (e.g. fix while going through a guide)
  • Promotes community responsibility
  • Exhibits loose coupling
1 Like

I actually disagree with this. Documentation that seems like itā€™s correct but isnā€™t causes far more damage, because it stops you from seeking the correct answer. Iā€™m not happy when people canā€™t find answers in the documentation, but itā€™s better than wrong answers.

Really? I just reviewed the backlog of pull requests and I donā€™t see anything egregiously out-of-date (wish I could say the same thing for Ember Data). Given that this is an all-volunteer staff, a lead time of a week or two to properly review doesnā€™t seem too bad, although thereā€™s room for improvement.

Weā€™ve tried similar strategies in the past and in general the quality was uneven and, in my opinion, reflected poorly on the project. As a compromise, how would you feel about expanding the documentation team? I am more than happy to open up triage to a larger team, although I would prefer they be vetted instead of implementing a ā€œone PR accepted = commit bitā€ policy.

2 Likes

Thatā€™s fair, I just wanted to start a discussion around it at least.

I guess I was referring to much to my own experience on trying to get feedback on documentation Iā€™d written for the BasicAdapter. I know everyoneā€™s busy, so I donā€™t like to pester too much, but at the same time, an open PR for documentation keeps a thread tied up in my head on managing tasks.

1,000x yes :smile: Would be great if this could include access to the Campfire (or a new documentation only Campfire) so that when documentation is being written queries can be answered quickly.

Onwards!

1 Like

This is one of my bug-bares too at the moment.