Code <-> Documentation workflow

👨‍💻 Framework Development 📖 Documentation
42

I agree. :+1: I think this will simplify the understanding of the features to document them

43

Awesome! Let’s try it then as see how it goes :slightly_smiling_face:

44

@juanma, @mburridge: At some point @santosguillamot and I proposed to be the ones helping you to document the next features because we want to understand what you need.

If you still want, we can do that for the Google Ad Manager package.

45

So should we be approaching one of you two and not the developer who implemented the feature when we want to document a feature and need more clarification/information?

46

@luisherranz @SantosGuillamot @mburridge I’ve tried to wrap up here the resources and conversations we’ve had regarding the documentation, specially those about the workflow for documenting new features

1. Documentation Sites

The main site affected by features documentation is

API Reference

Besides this one, we also manage the following sites

2. Resources

2.1 Which syntax/format to use when documenting API Reference docs

:point_right: Guidelines for API reference docs

in the WIKI of the API Reference docs repo there are the Guidelines for API reference docs with the criteria followed to document every piece of information (syntax, arguments, types, is mandatory, …). These guidelines takes into account the constraints we have for working with gitbook.

2.2 What is the workflow to follow to document a new feature after it’s released

:point_right: Code Releases
:speaking_head: Code <-> Documentation workflow

In the WIKI of the Docs repo is documented the Code Released workflow agreed w/ Dev team to document features after they’re released

2.3 What should be structure of a Feature Discussion to ease the documentation process after the release

:speaking_head: How can we improve the FDs process? → :zap: Mario’s proposal

Regarding this conversation, the most interesting proposal from a documentation point of view is having a Final Implementation section in every Feature Discussion that has been released

From the Final Implementation section proposal I’ve marked w/ :raising_hand_man: those that are most interesting for DevRel for features documentation

Final implementation

  • :raising_hand_man: Pull Request → Link to the PR where it was implemented.
  • :raising_hand_man: Requirements → For example, for the @frontity/yoast package, you have to install the Yoast plugin ^14.0
  • :raising_hand_man: 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.
  • :raising_hand_man: 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.
  • Technical explanation → How the feature was implemented. We explain the code
  • :raising_hand_man: :raising_hand_man: 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.

2.4 Are we going to use TSDocs for documenting the code?

:speaking_head: Code <-> Documentation workflow → Yes, as agreed on January 2021

This will affect anyone modifying the code of the themes/packages as these comments are required to pass the PR checking and being able to merge the PR’s

From here we can have a meeting if you want so we can clarify some final points.
For me the key things that would help DevRel to document new features are

:point_up: The creation of. The Final Implementation section and content suggested by Mario
:point_up: Following this workflow:

  • :one: The PRs of that feature have been merged and the Feature has been released
  • :two: The Final Implementation section is added to the FD
  • :three: The type: code release issue is created in the API Reference repo

What do you think?

1 Like
47

Thanks for the wrap up Juanma! Pretty useful :slightly_smiling_face:

In my opinion it seems we are aligned, so I think we can organize ourselves asynchronously. We have already started working with this workflow, but it doesn’t apply to old features. So let’s keep an eye and see what could be improved.

48

Excellent!

I’ve added a link to the wrap up to the Opening Post: Code <-> Documentation workflow

We must remember to update the wiki once we see if the new proposed process makes sense.

Apart from that, my only suggestion is to create a different Template for the Final Implementation, based on the Implementation Proposal template, but with the new questions suggested by @juanma.

The DevRel team will add or remove sections from that Template over time when they start doing real work and learn what they need and what they don’t.

What do you think?

49

Yes, that was our idea.

Actually, maybe you could do it with Mario and the developer who implemented the feature because the idea was that Mario would learn about your needs to incorporate them in our workflow, and the developer answers your technical questions.

What do you think @santosguillamot?

By the way, you mentioned that you wanted to work on the Google Ads Manager package, which was created by David, but you reached Michal, who is the supporter this week.

I guess we have to make a decision about that as well: Should you work with the original developer or the supporter?

In my opinion, it should be the original developer. Actually, sometimes times there will be more than one developer involved, so you should reach whoever wrote the Final Implementation.

50

I don’t fully understand it. We have this Final Implementation template, that is the one Juanma was referring to. It is also here as markdowwn. Do you mean to change it? I agree it will need some iteration.

Yes, sure. I can be there to analyze the process and the developer in charge of the feature to solve any technical question.

I agree it will be better to contact the Developer who wrote the Final Implementation, who should be the one with more information about the feature.

51

Oh, I thought it was Michal because he raised the issue in the docs repo. Also because Michal announced he’d merged it.

Maybe we should have some easy way of identifying attribution.

52

:question: :question: :question: :exclamation: :exclamation: :exclamation: :laughing:

53

That case is strange. Maybe I didn’t write the final implementation because I was on summer holidays? I don’t remember. The one who writes the FI is usually someone who has been involved on the implementation, so reaching the author should be enough. :thinking:

Anyways, for this specific case, yes, it’s better if you contact me instead of Michal. :slightly_smiling_face:

54

Haha, sorry. I meant once you start working on documenting new features again :sweat_smile:

55

There is another thing we need to work on regarding the Code <-> Documentation workflow: major releases.

We have the first one: @frontity/google-analytics version 2: Google Analytics package - #17 by luisherranz

We need to talk about what to do in these cases.

The DevRel team needs to decide:

  • How to update the docs.
  • How/where to create migration guides.
  • How to refer to the previous versions (info, APIs and so on).
  • …

And we should agree on what the Dev team should do in this cases:

  • Work on a new Feature Discussion?
  • Update the previous one?
  • Release a new Final Implementation that includes required migration steps?
  • …

cc: @SantosGuillamot @juanma

56

We had a meeting today to check the current status of the Code <> Docs workflow

The agreed workflow has been updated at Code Releases · frontity/api-reference Wiki · GitHub

The conclusions of the meeting are:

1 Like
57

@luisherranz this a difficult thing to manage with Gitbook right now.
Versions in Gitbook work at a site level and they cannot work at a section level

A good first approach to deal with these different major versions would be:

  • Having in the documentation the latest version available as the default option
  • Lower versions can be moved to subsections under the latest version
    • Migrations guides can be part of this page
  • We can refer to the different versions as:
    • @frontity/google-analytics latest one
    • @frontity/google-analytics@1.x previous ones
58

Sounds good :slight_smile:

59

I notice that sometimes more than 2 people are assigned for review of a docs PR (typically 1 dev and 1 devrel).

It can easily happen that both have worked on reviewing and correcting the same issues as it just did in wp-comments package docs by juanmaguitar · Pull Request #21 · frontity/api-reference · GitHub

My question is:

  1. Should we assign developers to review the docs PR? Do you see a clear benefit there? It’s an honest question - I don’t know have a strong opinion about it myself.

  2. If the answer above is “yes”, then I would suggest that we only assign one person to review a PR at a time. Once a PR is reviewed by 1 team member, the original creator can assign it to another team member. As the original PR creator is in charge of merging the PR once they deem it ready, there is no risk of having the reviewer merge unfinished changes.

    I’m aware that this process might at first seem a bit slower, but I think it’s not the case. I think that it fits rather nicely into the “blocked by default” mindset and just makes the process a bit more async.

Let me know your thoughts

1 Like
60

Hi @mmczaplinski

Yes, we will always need a review from a developer to assure we’re being accurate in our explanations and to review we’re not forgetting anything critical

The review from the other DevRel member is to check that our explanations are enough to understand the feature (taking the role of someone who read the docs about the feature for the first time). Also is a way to give visibility about the features documented

I think you’re right. We can assign first the review to the developer for accuracy and once we have his review we can add the other DevRel member as reviewer to check form, grammar and ways of explaining the feature

@mburridge what do you think?

2 Likes
61

Generally there doesn’t seem to be too much of a problem, the fact that this “conflict” happened on one occasion doesn’t necessarily mean there’s a problem that needs to be fixed.

But if it is a problem, or could become one, then assigning reviewers sequentially could work - at the risk of slowing the process down slightly.

I don’t like the idea of having a reviewer adding changes after the creator has merged the PR. The point of the review process is to end up with a version that everyone involved has agreed upon.

We definitely need to have a developer (the developer who worked on the feature) to review the docs to check for accuracy. However, the developer is so close to the code and understands it so well that they bring that existing understanding to the review of the docs and may fail to see that the description is not sufficient for someone without the same knowledge to understand it - hence having the other devrel review the docs.

I think it’s important for the developer reviewing the docs to try to put aside their knowledge of the feature and to try to read the docs with the mindset “is there enough information and detail here for anyone to understand this?”.

4 Likes