Add ADR for removal of Smartdown #2053
Conversation
This documents our decision to remove Smartdown from the Smart Answers project. See Documenting Architecture Decisions[1] for some background of ADRs. See presentation/adr-001[2] and backdrop/adr-001[3] for examples of ADR use within GDS. [1]: http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions [2]: https://github.com/openregister/presentation/blob/master/doc/arch/adr-001-remove-kafka.md [3]: https://github.com/alphagov/backdrop/blob/master/doc/arch/adr-001-implementation-language.md
|
I plan to revisit this but I'd appreciate any feedback you might have, @floehopper. |
|
I'll come back to this again, but here are a couple of quick initial poorly-expressed thoughts while I think of them:
|
Based on feedback from @floehopper.
|
Thanks, @floehopper. I've now incorporated your comments. Feel free to suggest any other amendments. How does this look to you, @dsingleton? Are there any obvious gaps in the document? |
|
I've only had time to skim this, but i'd want to give some proper feedback before merging, so could you hold off a bit? Mostly reflecting the initial aims of Smartdown (eg, publishable/workflowable representation). |
@dsingleton: Would this not be more appropriate in a separate ADR, possibly in the Smartdown repo? |
|
I've spoken to @dsingleton and we've agreed that documenting Smartdown should be in a separate ADR. I'm going to rebase this on master in preparation for getting it merged. |
|
@floehopper: Is there anything else you want to add to this or can I merge it? |
|
I think you should go ahead and merge it. I think what you have is pretty comprehensive and we can always add stuff later. |
|
I'm happy to write up an ADR 0 for the addition of Smartdown (could you add a card to the trello and put my face on it? ta). I've got a couple of small suggestions before merging. I'll add them now. |
|
|
||
| Smartdown made it easier for content designers to edit questions and outcome content, but was quite restrictive when it came to defining the rules of the Smart Answer (see the rules in [pay-leave-for-parents/partner_earned_more_than_lower_earnings_limit][spl-complicated-next-node-rules], for example). | ||
|
|
||
| Smartdown didn't match Ruby Smart Answers in terms of features. Adding support for these features to Smartdown would have required extensions to the grammar and hence the parser. The cost of this would've been relatively high, especially considering that Ruby Smart Answers already had all the functionality we needed (apart from multiple questions-per-page). |
There was a problem hiding this comment.
Ruby Smart Answers already had all the functionality we needed
I think it would be worth qualifying that one of the benefits/functionality of Smartdown was the intent for it to be pased over an API, allowing publishing workflow. The decision here (which I 👍 with) is to not attempt to solve that problem, and focus on making the Ruby format as simple and accessible as possible, on the assumption of high turnover of people working on it.
There was a problem hiding this comment.
I think/hope I've partially addressed this by adding a sentence to the decision section in d3b19cd.
I'm less sure about mentioning that Smartdown was designed to be passed over an API. That feels like a candidate for the Smartdown ADR to me. What do you think?
|
Added some comments about clarifying the intent of the ADR, it's good, but feels a bit focused on what and less of the why, which is the important bit to preserve. |
Done - https://trello.com/c/4QGJGBGQ/130-add-architecture-decision-record-adr-about-smartdown |
@dsingleton made me realise that I was conflating the use of ERB outcomes and the removal of Smartdown when I wrote this. I think the use of ERB makes it easier for content designers to edit Smart Answer outcomes, _not_ the removal of Smartdown.
@dsingleton pointed out that the use of "project" was confusing as it could mean this application or the Smart Answers ecosystem. I think we could argue that both have been simplified but it's certainly more obvious that the Smart Answers app has.
Based on feedback from @dsingleton.
|
@dsingleton: Thanks for the feedback! I've attempted to address it in the more recent commits and would appreciate you taking another look when you have a minute. |
chrisroos
changed the title
Closes PR #2053. Manually merged from add-architecture-decision-record-about-smartdown-removal. I wanted to update one of the commit messages but didn't want to lose the discussion on the pull request, so I've manually merged it.
|
I've merged this in 968867b. Any further discussion can happen as a new pull request. I manually merged it (rather than rebasing on master and force-pushing to this branch) in order to retain the discussion in here. |
chrisroos
deleted the
add-architecture-decision-record-about-smartdown
branch
|
👍 |
This documents our decision to remove Smartdown from the Smart Answers project.
See Documenting Architecture Decisions1 for some background of ADRs.
See presentation/adr-0012 and backdrop/adr-0013 for examples of ADR use
within GDS.
Expected user-facing changes