Improving our workflow / specs

[Mohammer5]

@dhis2/team-platform

Currently we're having a fair amount of uncertainty when working on apps when it comes to what's supposed to be supported or how things are supposed to work. This stems from not having proper specifications. The best source of information for many things is talking to @larshelge. I think in the short term there's not way around this, but we can improve our workflow and slowly grow the spec coverage over time.

I've talked to @cooper-joe about this at the end of last year and we've agreed that the following workflow could work quite well:

• Before putting any work into coding, the design/ux team and stakeholders gather functional & design specs in google docs
  • This has worked quite well for the data entry app. There are a few things here and there that were still unclear, but the general idea of how the app is supposed to work was laid out quite well
  • @cooper-joe was able to write down his ideas right when he had them, no need to create a PR with feature files or Jira issues for different things
• Once we start working on the app / feature, we put everything that's in the google docs into feature files.
  • Once the feature files are complete, they are the source of truth as it's quite hard to notice changes in the google docs
• (One things that might be noteworthy, is: We should not put the design of the components / app into the feature files, only behavior)

One of the biggest challenges right now is to work on code that hasn't been touched in a while (especially porting struts apps to modern apps). Knowledge of how things are connected, decisions that were made on the fly during development, etc have faded away and have been forgotten to some extend. If we keep the specs growing by forcing ourselves to write them before working on code, we can slowly but surely grow confidence when working on code that's been spec'ed. At the same time we don't block the initial work as it's fairly straight forward to contribute to google docs, especially for people who're not familiar/comfortable with writing feature files.

---

Open question: How can we achieve having specs for feature requests in Jira as often core devs just create a Jira issue instead of writing specs in google docs?

[mediremi]

Having an issue template for feature requests in Jira could be useful in nudging developers into expanding on the feature specs.