search

spacetelescope / style-guides

An opinionated guide on how we work.
Creative Commons Attribution 4.0 International
55 stars 33 forks source link

Stuff that doesn't seem like style guides #21

Closed arfon closed 6 years ago

arfon commented 6 years ago

Heya, there's a fair amount of stuff in here that I'm not convinced are style guides. Examples would include:

At lot of the open tickets are what I would describe as 'workflow' guides rather than style guides. While I think defining workflows is a really good idea, it's just not obvious that they should be in this repo.

Thoughts @stscicrawford @eteq?

eteq commented 6 years ago

@arfon - I agree with you from a "what these words mean" point of view, but from a "what software design and maintainence processes should be known across the institute" perspective, I think these do fit. And I would worry about there being multiple places that people need to look - "style guide" seems more important/approachable/likely for folks to read than "workflow guide", but I think both are ~ equal in importance for getting work done maintainably.

Put another way: I think this is what a lot of the INS folks don't know but want to know. It's "style of the code and code-writing process" rather than just "style of the code".

Also, I think at least #12 is related to some of the stuff in the style guides, because the whole motivation for a lot of the packaging stuff is to simplify release workflows. That doesn't mean it has to be a style guide, but it means we want the style guide to harmonize with wherever those guidelines exist.

eteq commented 6 years ago

Although having said all that: if the intent is for the "readable" versions of these guides to be somewhere else, maybe it doesn't matter, and we should just move that stuff to "spacetelescope/workflow-guides" for development and just present/link them together when "advertised".

stscicrawford commented 6 years ago

Yes, my creation of sections is partially based off the LSST Developer guidelines which to be fair isn't just style but also the developer guidelines. These include a lot of information about workflow and communicating.

I agree with @arfon that these sections would not be included in a strict style guideline, but I also agree with @eteq that what we want to create is the "style for writing code" -- ie the developer guidelines.

I usually favor having things in one repository, but I'm also fine with having these in separate repositories or renaming this one to be the developer's guide to be more inclusive.