In the previous team call, Weekly Team Call (March 12th, 2020)
there was a suggestion that updating documentation becomes a requirement for a release. With the validation process for now being, maintainers sign off on a release.
I’m looking to make more specific what “the bar” is for documentation. Now and going forward.
Two things I would like to point out starting the discussion is:
We’re in a Beta stage, so I believe the target audience to aim for currently would be (potential) contributors to SourceCred and/or Beta pilot partners.
Since contributors’ time is one of our main bottlenecks, I believe low-hanging fruit suggestions are better than painting ideal scenarios right now.
I think it would be good to have a (blog-like) introduction of new features / major changes.
These would have an outline of: What is it? Why is it useful? How do I (technically) use this?
I believe, by doing this only for major features/changes and in a blog-like introduction only (rather than maintaining a full technical documentation of all features across versions). We keep the administrative burden low. While still putting some pressure to document these major changes in a format that we could share more broadly with the target audience.
I think this is a good plan @Beanow. @anon60584824 I think does a good job of fleshing this out into a more general strategy.
@anon60584824 I think your proposed workflow is good, and generally adheres to OSS common/best practices. A docs website appears out of scope for this release, but moving forward it makes sense to create and update.
I think a rather technical blog (with content re-usable for technical doco) for this release could be published on the SourceCred medium. This could then be put out on Twitter, maybe reposted in a Discourse post.
What if instead of a blog post, we had a brief guide? E.g. a guide on using the Discourse plugin (how to use it standalone via the sourcecred.js discourse command, explanation of the types of nodes and edges, explanation of like-minted-cred).
We could publish the guide like a blog post, but the guide would be maintained as source-of-truth in sourcecred/docs. The key difference, IMO, is the expectation that we’ll keep guides up to date, whereas the blog post would likely rot pretty quickly. E.g. when we land the quality of life update, that will change the CLI interfaces, so we would update the guides.
Then, as we roll out a better website, the guides can all get included in a tutorials section.
Yeah that’s my thinking.
Having some documentation is much better than having none. And if a small commitment can ensure that, it’s a lot less painful than having to backtrack through undocumented features.
Yes, I think we have something in place to encourage developer docs in our regular workflow.
When reviewing code, a heuristic is to make it easier to review.
Simple code with good naming, helpful comments, commit descriptions and comprehensive test suites will make a reviewers’ day. A big blob of undocumented, untested spaghetti would probably be rejected for that reason even if correct.
What we don’t have currently is push back for lack of user documentation. So my focus for this proposal is on that.
You’ll have to teach me how to do that one day. Seems like a good bit of overhead to me atm
I had the thought of using a tag/category on Discourse to house these posts first. Medium feels like an interesting channel to cross post on for additional exposure, but I’m not too comfortable to make this our primary technical guides channel.
To me, that kind of brief guide is the purpose of that blog post. So, I think we agree on the sort of content we’re looking for
I fear that would be too steep a requirement and end up in “who’s going to do it?” territory.
Having a per-feature blog posts for a release as the minimum requirement, raises the bar over previous releases.
And I think this blog-rot gives diminishing returns. Any documentation is significantly better than no documentation. Perfectly updated documentation is only marginally better than somewhat outdated documentation.
So by keeping the bar low, at one-off documentation, I think we’re getting the most out of the diminishing returns, without putting a lot of requirements on release packagers.
#1679.
that’s my thinking.
Having some documentation is much better than having none. And if a small commitment can ensure that, it’s a lot less painful than having to backtrack through undocumented features.
