How can we improve the FDs process?

đź—Ł Feature Discussions
1

In the latest retrospective, we all agreed that there is room for improvement regarding the Feature Discussions process. These are some questions where we should take a decision and my opinion right now (I want to take a look at current Feature Discussions to have a stronger opinion):

  • What should we include in the opening post?: Usually in a forum, the opening post is not changed because it’s supposed to be a conversation. This way, if a new person starts reading the thread, it just makes sense. However, we think it could be useful to have the current status or the final implementation in the opening post as well, so if someone just wants to understand how to use a feature, they don’t have to look for the info in the thread, it’s available in the opening post. Should we modify the opening post? If so, should we keep the description provided at first so the conversation makes sense?

    I feel that both things are important and they should be easy to find, so I think I would keep the opening content and include a new section at the bottom with the Current Status/Final Implementation, with a warning saying this information has been added afterwards.

  • Should we differentiate between functionalities/requirements and implementation?: Right now, we’re only talking about the implementation process and we’re kind of mixing everything.

    At first sight, I feel it would make sense to differentiate between the functionalities/requirements that could be needed for a feature, and how to implement them. I would be the owner of the first part, which functionalities are included and which are moved to a new FD, and Luis of the second one.

  • How would we divide between functionalities/requirements and the implementation?: Does it make sense to have everything in the same thread or should we split it?

    In my opinion, everything should be in the same thread as they are really related. Sometimes, while working in the implementation proposal or the final implementation, we will come up with new ideas about functionalities or requirements. We could include a new sections for functionalities and another one for requirements.

  • Are templates useful as they are right now? How could we improve them?: We have a template for the opening topic, which encourages users to think about useful information like examples and possible solution, and a detailed template Luis prepared for the Implementation proposal. Is there any information missing or something you feel it’s not necessary?

    I would include new sections for functionalities or requirements in the opening topic, although we could just delete them if they are not relevant for any Feature. I feel the IP template is great, although I’m not writing them. And I think we should have something similar for the Final Implementation as well.

  • Should we keep using User Stories? If so, at which point?: We feel User Stories aren’t being useful right now and, in fact, we’re not using them that much. They can be confusing for some users. Maybe they could be useful just for the implementation, so would it make sense to just use them in the Implementation Proposal, which is what we’ll use for the final implementation?

    As it isn’t still clear how we are going to work with functionalities and the implementation I would stop using User Stories for now but I would try to think, each time we write an IP, if having user stories could be useful and how. I don’t have a strong opinion here, I want to think more about it

EXTRA: The way I see it, a possible workflow of a Feature workflow could be the following:

  1. Suggest a feature: We have an idea and we should provide: Description, Examples, Possible functionalities, Possible requirements and Possible solution. They are not all required if it’s still not clear.

  2. Functionalities and requirements discussion: We start discussing if that feature makes sense and which functionalities/requirements could be relevant. (Consider as many as possible as it could affect the implementation).

  3. Research how to implement it: At this point, we could research how to develop it. Even if it’s a small feature and we don’t add the needs research tag, we usually do a small research to come up with an Implementation Proposal.

    Although we won’t implement all the functionalities, we should keep them in mind during the research. During the research we can discover new functionalities we’ll have to consider.

    We should start a conversation as well about the implementation and come up with an Implementation Proposal, that should be enough to start implementing the v1.

    In this IP we should sum up all the decisions we have made: which functionalities are going to be included in the v1 and how we’re planning to implement them.

  4. Development: We work on it and release a beta version. We start testing it, and ask the community to test it. At this point the implementation may have change, or even the functionalities we are going to add for the v1 (maybe we discovered one functionality is much harder and we decide to postpone it), so we should sum up the Final implementation, similar to the Implementation Proposal, with the final status, with the settings and everything that has changed. We could also include here a demo.

2

@dev-team Guys, could you take a look at this and share your thoughts please?

3

Agreeing with your points here @SantosGuillamot :slight_smile:

In particular, I think this is a good improvement:

Yeah, I like that. It’s dead simple but it works I think. And you can always use the “Quote” functionality of Discourse to discuss particular points in a thread-like manner, like we always did.

4

I agree with all the things that Mario said.

About the Opening Post: I think writing things like the Implementation Proposal and the Final Implementation there (and only there) would also be confusing unless they are also in the normal flow of the conversation. So I would try links instead of actual text. I don’t know about quotes like Michal said. Maybe those can work as well.

5

Let me add some feedback from DevRel point of view as we need to deal with these FD threads to understand the features to documents them

It would be very useful for understanding how the feature must be used to have a specific post in the thread with the Final Implementation. It would also be useful to include in the thread a Loom video with a brief explanation on how to use it in a project

This Final Implementation post (and optionally a Demo video post) can be linked from the initial post (the one that has the feature description and so) so all the information is accessible from the same place

I think so, Also I think, both should be linked from a single place (initial post with Feature defintion)

Whatever is required to full understand the feature, even if these resources are links to other posts in the same thread with the final implementation, demo videos or some other info

Having a specific template for each type of info would help. This can be posted at any point of the thread and then it can be linked from the Feature’s definition (first post of the thread w/ the feature’s definition).

1 Like
6

Thanks for the feedback guys :slightly_smiling_face: I will be working on this and I’ll keep you updated. It seems we are more or less aligned with the possible solution.

7

I have been thinking about the different templates we could use. I feel we should try to keep them as simple as possible but consider most of the cases in every Feature. We have to keep in mind that, depending on each feature, some sections won’t be relevant and they could be removed.

After taking a look at our own Feature Discussions and how other open source projects deal with it, this is my initial idea:

  1. Opening post template.
  2. Implementation Proposal template.
  3. Final implementation template.

@dev-team I would specially appreciate your feedback on the Final implementation template, as you are the ones writing them down. Some questions that come to my mind:

  • Should we include a summary/TLDR?
  • Is there something missing or something included that you think is not relevant?

1. Opening post template

Description

Try to give a detailed explanation of what do you expect of this feature.

Examples

Do you know examples that could inspire the community? Let us know! -->

Functionalities

Initial list of functionalities that would be nice to include in this feature!

Requirements

Initial list of requirements and constraints that need to be met.

Dependencies

List of Feature Discussions that need to be finished before this one.

Possible solution

If you have already thought of a possible solution, let us know!

2. Implementation Proposal template

We can keep using the one Luis created, I think it’s pretty good, it covers most of the cases.

3. Final implementation template

Pull Request

Link to the PR where it was implemented.

Requirements

Sometimes, there will be some requirements to use the feature. For example, for the @frontity/yoast package, you have to install the Yoast plugin ^14.0.

Functionalities

List of the final functionalities that were included in the final implementation, with a detailed explanation of each one: how it works, how to use it (install a package? add a new setting?) and a code example/screenshot/quick video if relevant.

Out of Scope

List of the functionalities that were finally discarded or slated for a future time. Until we finish the implementation this may change, so I think is good to do a recap here.

API changes

Backward compatible changes

List of the changes that are backward compatible.

Breaking changes

List of the breaking changes and how to migrate your old project.

Deprecated APIs

List of the deprecated APIs.

I think this section could be also pretty useful for the releases, to sum up there all the API changes.

Technical explanation

In some cases we explain in detail how the feature was implemented. We explain the code, not only the things we do. I feel it could be useful to maintain that new feature in the future and improve it, but I’m not sure. What do you think? A couple of examples:

Demo

Full video explaining how to use the feature and its functionalities. This can be added afterwards. We could even include a CodeSandbox like we did with the wp comments.

1 Like
9

Great work @SantosGuillamot :slight_smile:

I’m sure for some features not all of the fields of the Final Implementation are going to be applicable, but in general it’s better to have a choice.

I would only like to add that with the more detailed and structured Final Implementation that you’ve proposed, perhaps it should be the final “source of truth” for implementing the documentation as well instead of the issue in github docs.

I’ve proposed it in the Code <–> Documentation thread

10

It totally makes sense. Let’s continue that conversation in the other topic but I agree we should keep improving the Final implementation posts until they are self explanatory for the documentation as well.

11

I like it as well! :slightly_smiling_face:

I especially like the idea of the final video and the codesandbox explaining how the new feature works not only to make the documentation easier to do, but also the announcement, newsletter and community users interested in the feature.