#34 review of the new project-tracking doc
Closed 2 years ago by ppisar. Opened 5 years ago by langdon.
fedora-docs/ langdon/modularity review-of-project-tracking  into  master

@@ -1,43 +1,66 @@ 

  = Project Tracking

  

- The work and an overall progress is being coordinated and tracked on a https://tree.taiga.io/project/modularity-wg/epics[**Modularity WG Kanban Board**].

+ The work and overall progress is being coordinated and tracked on a https://tree.taiga.io/project/modularity-wg/epics[**Modularity WG Kanban Board**].

"…tracked on a…" should be "…tracked on the…"

  

- User feedback such as bugs and feature requests is being collected in a https://pagure.io/modularity/issues[**Modularity issue tracker**].

+ User feedback, such as bugs and feature requests, is being collected in a https://pagure.io/modularity/issues[**Modularity issue tracker**].

Same here, "…collected in a…" should be "…collected in the…"

  

  == What is being tracked

  

- 1. https://tree.taiga.io/project/modularity-wg/epics[**Goals (epics)**] — A specific definition of a state we want to achieve, ideally a https://en.wikipedia.org/wiki/SMART_criteria[SMART] goal. Setting a direction of the project.

- 2. https://tree.taiga.io/project/modularity-wg/kanban[**Actions (cards)**] — Tasks that get us closer to a specific goal. Defining actionable work items contributors can complete.

+ 1. https://tree.taiga.io/project/modularity-wg/epics[**Goals (epics)**] — A specific definition of a state we want to achieve, ideally a https://en.wikipedia.org/wiki/SMART_criteria[SMART] goal.

+ Setting a direction of the project.

Same indefinite vs. definite pronoun thing plus I'd avoid the gerund here. E.g.: "To set the direction of the project."

+ 2. https://tree.taiga.io/project/modularity-wg/kanban[**Actions (cards)**] — Tasks that get us closer to a specific goal.

+ Defining actionable work items contributors can complete.

"To define actionable…"

  3. https://pagure.io/modularity/issues[**Feedback (issues)**] — User feedback such as bugs, ideas, questions. Influencing the project from outside.

  

  == How we operate

  

- We work with an Agile mindset. We have designed our system to be transparently communicating our goals and intentions without the need of understanding every single piece of work that is being done. It also allows us to display actionable tasks that are clearly defined and prioritized so anyone can help us move forward.

+ We work with an Agile mindset.

+ We have designed our system to transparently communicate our goals and intentions without the need to understand every single piece of work that is being done.

+ It also allows us to present actionable tasks that are clearly defined and prioritized so anyone can help us move forward.

  

- Because Agile is not making things up as we go, but rather iteratively working towards specific goals, the first thing that needs to exist are goal definitions.

+ Because an Agile process is not "making things up as we go," but rather "iteratively working towards specific goals," the first thing that needs to exist are goal definitions.

  

  === Setting and tracking the goals

  

- Goal definitions are ideally SMART — specific, measurable, actionable, relevant, and time-bound. At the absolute minimum, they always must have a clearly defined purpose — so we know why do we want to achieve them, and a definition of done — so we know when exactly are they achieved. This way we can communicate the direction of the project.

+ Goal definitions are ideally SMART — specific, measurable, actionable, relevant, and time-bound.

+ At the absolute minimum, they always must have a clearly defined purpose — so we know why we want to achieve them, and a definition of done — so we know when they achieved.

+ This way we can communicate the direction of the project.

  

- Goals (epics) are owned by a single person who acts as a feature driver. The owner doesn't necessarily do all the work, but makes sure that actionable tasks that lead towards a completion exist at all times, and is responsible for the goal being completed. This way the project can be scaled across a large community of contributors.

+ Goals (epics) are owned by a single person who acts as a "Feature Driver" or "Epic Owner" (to use the Tiaga term).

"Tiaga" → "Taiga"

+ The owner doesn't necessarily do all the work, but makes sure that actionable tasks that lead towards completion exist at all times, and is responsible for the goal being completed.

+ By de-centralizing leadership, the project can then be scaled across a large community of contributors.

  

- Epics are defined in the https://tree.taiga.io/project/modularity-wg/epics[Epics view of our board]. This view is used for strategic planning and for monitoring the overall progress of the project. It also allows to drill down into idividual epics for more specific details about each goal.

+ Epics are defined in the https://tree.taiga.io/project/modularity-wg/epics[Epics View of our board].

+ This view is used for strategic planning and for monitoring the overall progress of the project.

+ It also allows one to drill down into idividual epics for more specific details about each goal.

  

- The specific epic detail shows the purpose of the goal, the definition of done, and other information such as a delivery deadline. It also lists all the actions (cards) that lead to a completion of this epic. Epic owners use this view to define and manage individual cards.

+ The details of a specific epic shows the purpose of the goal, the definition of done, and other information such as a delivery deadline.

"show"?

+ It also lists all the actions (cards) that lead to the completion of this epic.

+ Epic Owners use this view to define and manage individual cards.

  

  === Making progress

  

- To work on the project, contributors visit the https://tree.taiga.io/project/modularity-wg/kanban[Kanban view of our board] showing all existing cards sorted into different columns, each representing a specific state. Contributors can choose any card in the "Next" column they want to work on.

+ To work on the project, contributors visit the https://tree.taiga.io/project/modularity-wg/kanban[Kanban View of our board] showing all existing cards sorted into different columns, each representing a specific state.

+ Contributors choose *any* card in the "Next" column they want to work on.

Why the emphasis?

  

- To work on a specific card, contributors can simply assign themselves to any card in the "Next" column and move it to the "In Progress" column. This way they indicate to other contributors that this card is already being worked on.

+ To work on a specific card, contributors can simply assign themselves to any card in the "Next" column and move it to the "In Progress" column.

+ This way they indicate to other contributors that this card is already being worked on.

I'd drop "already" in this sentence.

  

- While working on a card, updates can be posted to the comment section of the card. Contributors can also mention other people in the comments to ask questions or to notify them about specific information. It is also encouraged to coordinate with other using the xref:community.adoc#_channels[usual communication channels] such as IRC.

+ While working on a card, updates should be posted to the comment section of the card.

+ Contributors can also mention other people in the comments to ask questions or to notify them about specific information.

+ It is also encouraged to coordinate with others using the xref:community.adoc#_channels[usual communication channels] such as IRC.

+ However, the card should not be treated as "documentation," rather just a communication mechanism about the work.

+ The card has a limited lifespan and will, eventually, be archived.

+ As a result, documentation should land elsewhere, wherever appropriate for the task.

  

- When a card is complete, contributors are expected to post an update to the comments, and move the card to the "Done" column in the https://tree.taiga.io/project/modularity-wg/kanban[Kanban view of our board]. This step updates the progress of the epic the card belongs to which is useful for tracking progress.

+ When a card is complete, contributors are expected to post an update to the comments, and move the card to the "Done" column in the https://tree.taiga.io/project/modularity-wg/kanban[Kanban View of our board].

+ This step updates the progress of the epic the card belongs to which is useful for tracking progress.

Is there a way to phrase this without doing "… progress … progress …"? This sounds tautological to me.

  

- If new actions appear as a result of a card completion, contributors should coordinate with the Epic owner about creating new cards for the new actions to ensure there is always next step in the queue.

+ If new actions appear as a result of card completion, contributors should coordinate with the Epic Owner about creating new cards for the new actions to ensure there is always a next step in the queue.

+ This communication is also important to make sure the Epic Owner understands the new cards as they are responsible for making sure it happens.

  

  === Reporting issues

  

- Issues such as bugs or feature requests can be created by anyone in the https://pagure.io/modularity/issues[Modularity issue tracker]. This issue tracker is then processed by the team and new cards or even epics may be created as a result. Separating user feedback from the work lowers the pressure on the person who reports the feedback — they don't have to understand our tracking system. 

\ No newline at end of file

+ Issues such as bugs or feature requests can be created by anyone in the https://pagure.io/modularity/issues[Modularity Issue Tracker].

+ The issue tracker is then processed by the Working Group and new cards or even epics may be created as a result.

+ Separating user feedback from the "work" lowers the pressure on the person who reports the feedback — they don't have to understand the working group's tracking system. 

\ No newline at end of file

  • introduced line breaks per sentence (per recommendation from docs people)
  • grammar clean up
  • language clean up
  • minor content addition pointing out 'cards are not docs'

Splitting these into multiple commits would make it easier to review.

I'll take a look.

"…tracked on a…" should be "…tracked on the…"

Same here, "…collected in a…" should be "…collected in the…"

Same indefinite vs. definite pronoun thing plus I'd avoid the gerund here. E.g.: "To set the direction of the project."

Is there a way to phrase this without doing "… progress … progress …"? This sounds tautological to me.

@langdon, let me know if you want a hand in splitting the changes up (as per the bullets in your first comment).

@langdon, let me know if you want a hand in splitting the changes up (as per the bullets in your first comment).

personally, I would just merge the change, then do another set of edits. Perhaps we could do the "line breaking on periods" part as one commit then language changes after. However, as it is just text, I am not sure how important commit history is. Let me know your ( @nphilipp, @psabata, @asamalik ) preference(s), im happy to do either, but that is my opinion.

Fine with me to merge and change on top (though I have to ignore my pedantry gland a little there :wink:).

Thanks @langdon for the PR and thanks others for suggestions. From my side:

  • +1 introduced line breaks per sentence (per recommendation from docs people)
  • +1 grammar clean up
  • +1 language clean up
  • -1 minor content addition pointing out 'cards are not docs' — My thinking: if the card isn't about writing documentation, there is no documentation. It doesn't apply in general. Also, that page should be as short as possible — it's basically a cheat sheet. Other pages with more details are coming.

@langdon So I propose, on top of the feedback above, we only keep the new lines and grammar checks.

BTW The "one sentence per line" rule is to make change reviews easier. In this case, it kind of worked the opposite way, because that was the change + grammar + language + content changes, all in a single commit. So everything looks changed.

I'm sorry but it seems that none of the edited sentence exists in the current documentation. I will close this pull request without merging.

Pull-Request has been closed by ppisar

2 years ago
Metadata