Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add ADR for removal of Smartdown #2053

Closed

Conversation

Projects
None yet
3 participants
@chrisroos
Copy link
Contributor

commented Nov 4, 2015

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

  • None
WIP: Add ADR for removal of Smartdown
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
@chrisroos

This comment has been minimized.

Copy link
Contributor Author

commented Nov 4, 2015

I plan to revisit this but I'd appreciate any feedback you might have, @floehopper.

@floehopper

This comment has been minimized.

Copy link
Contributor

commented Nov 4, 2015

I'll come back to this again, but here are a couple of quick initial poorly-expressed thoughts while I think of them:

  • The state of many of the Ruby Smart Answers would've made it hard to convert them to Smartdown without extensive refactoring.
  • Adding new features to Smartdown would generally have needed extensions to the grammar and hence the parser. I think the cost of adding new features to Smartdown would've been relatively high, especially considering that Ruby Smart Answers already had all the functionality we needed (apart from multiple questions-per-page).
@chrisroos

This comment has been minimized.

Copy link
Contributor Author

commented Nov 9, 2015

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?

@dsingleton

This comment has been minimized.

Copy link
Contributor

commented Nov 10, 2015

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).

@chrisroos

This comment has been minimized.

Copy link
Contributor Author

commented Nov 11, 2015

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?

@chrisroos

This comment has been minimized.

Copy link
Contributor Author

commented Nov 16, 2015

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.

@chrisroos

This comment has been minimized.

Copy link
Contributor Author

commented Nov 16, 2015

@floehopper: Is there anything else you want to add to this or can I merge it?

@floehopper

This comment has been minimized.

Copy link
Contributor

commented Nov 16, 2015

I think you should go ahead and merge it. I think what you have is pretty comprehensive and we can always add stuff later.

@dsingleton

This comment has been minimized.

Copy link
Contributor

commented Nov 16, 2015

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).

This comment has been minimized.

Copy link
@dsingleton

dsingleton Nov 16, 2015

Contributor

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.

This comment has been minimized.

Copy link
@chrisroos

chrisroos Nov 18, 2015

Author Contributor

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?


## Consequences

It's easier for content designers to edit Smart Answer outcomes.

This comment has been minimized.

Copy link
@dsingleton

dsingleton Nov 16, 2015

Contributor

This seems to contradict an earlier point "Smartdown made it easier for content designers to edit questions and outcome content". AFAIK there wasn't a lot of instances where smartdown was edited by content designers (other than during SPL development), due to the small number of smartdown smart answers.

This comment has been minimized.

Copy link
@chrisroos

chrisroos Nov 18, 2015

Author Contributor

I think I was conflating the use of ERB outcomes and the removal of Smartdown. I think the use of ERB makes it easier for content designers to edit Smart Answer outcomes, not the removal of Smartdown. I've removed this line in b140edb.


It's easier for content designers to edit Smart Answer outcomes.

The Smart Answers project is simpler now that there is one less way of authoring Smart Answers.

This comment has been minimized.

Copy link
@dsingleton

dsingleton Nov 16, 2015

Contributor

By project do you mean app, or the whole eco-system? This makes sense to me as app, as not having the two sets of presenters/libs does greatly simplify the app 👍

This comment has been minimized.

Copy link
@chrisroos

chrisroos Nov 18, 2015

Author Contributor

I've clarified by changing "project" to "application" in 984985c.


The Smart Answers project is simpler now that there is one less way of authoring Smart Answers.

Developers new to the Smart Answers project have one less thing to learn to get up to speed.

This comment has been minimized.

Copy link
@dsingleton

dsingleton Nov 16, 2015

Contributor

I think this is the main benefit, and would be worth making the point stronger. We optimised for maintenance, a standardised format with "one way to do it" and BAU throughput. Similarly this applies to the "Decision" section too.

This comment has been minimized.

Copy link
@chrisroos

chrisroos Nov 18, 2015

Author Contributor

I think/hope I've addressed this by adding a sentence to the decision section in d3b19cd.

@dsingleton

This comment has been minimized.

Copy link
Contributor

commented Nov 16, 2015

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.

@chrisroos

This comment has been minimized.

Copy link
Contributor Author

commented Nov 18, 2015

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).

Done - https://trello.com/c/4QGJGBGQ/130-add-architecture-decision-record-adr-about-smartdown

chrisroos added some commits Nov 18, 2015

Remove inaccurate consequence
@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.
Clarify that the app is simpler
@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.
Update Decision section
Based on feedback from @dsingleton.
@chrisroos

This comment has been minimized.

Copy link
Contributor Author

commented Nov 18, 2015

@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 chrisroos changed the title WIP: Add ADR for removal of Smartdown Add ADR for removal of Smartdown Nov 25, 2015

chrisroos added a commit that referenced this pull request Nov 25, 2015

Merge pull request #2053
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.
@chrisroos

This comment has been minimized.

Copy link
Contributor Author

commented Nov 25, 2015

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 chrisroos closed this Nov 25, 2015

@chrisroos chrisroos deleted the add-architecture-decision-record-about-smartdown branch Nov 25, 2015

@dsingleton

This comment has been minimized.

Copy link
Contributor

commented Nov 25, 2015

👍

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.