Required documentation for releases

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:

  1. 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.
  2. Since contributors’ time is one of our main bottlenecks, I believe low-hanging fruit suggestions are better than painting ideal scenarios right now.

With that said, here’s what I would propose for Release v0.5.0 :rocket: #1679.

In this release there’s a list of new features:

New features:

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.


Inviting everyone’s feedback and thoughts here. But some in particular I would like to poke: @decentralion @s_ben @vsoch @wchargin

1 Like

I think this is a sound suggestion - I typically write user documentation / tutorials whenever there is a change or release, and it’s an easier strategy to do it marginally with changes over not doing it, and then realizing your software is lacking in documentation. To be clear, there are two kinds here - developer docs (e.g., docstrings, notes for future developers) and user documentation (Hello friend, here is how this works!) and both are important. I can see having a blog like introduction that describes little bits, and then links to more detailed documentation, along with other useful resources. In case it’s helpful, here are some examples I’ve done:

I generally see the workflow like this:

  1. develop code (and write markdown docs as you go) - at least for some languages you can interactively test and write examples as you develop it, so you are sure you cover all points.
  2. publish release and prettied docs (e.g., markdown goes nicely into GitHub pages, of course this requires a jekyll site hosted with or alongside the code base)
  3. write post about changes, possibly a tutorial, link to both official docs and tutorial and other supporting links
  4. share via blog, social media, etc.

I think it’s helpful to do points 1-3 close to the time that the code is developed so the details are fresh in your mind, and then 4 comes when it’s ready to get attention. By the time the release comes, there should be no extra work other than linking to said content.

2 Likes

I think this is a good plan @Beanow. @vsoch I think does a good job of fleshing this out into a more general strategy.

@vsoch 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 :smiley: 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 :stuck_out_tongue:

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.

1 Like

I’m not sure there is much to teach, I think that I just have a lot on my mind that most easily comes out through my fingers :slight_smile: https://vsoch.github.io/archive/ I strongly suggest MMORPGs to get practice with quick typing, if anything!

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 :smile:

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.