Skip to content

Conversation

@ksc-odoo
Copy link
Contributor

@ksc-odoo ksc-odoo commented Aug 2, 2022

Task ID: 2850055

@ksc-odoo ksc-odoo requested a review from mivu-odoo August 2, 2022 19:28
@robodoo
Copy link
Collaborator

robodoo commented Aug 2, 2022

@ksc-odoo
Copy link
Contributor Author

ksc-odoo commented Aug 2, 2022

Hi @mivu-odoo

here's the social marketing doc for v14. If you could please review it at your earliest convenience, that would be greatly appreciated.

Once you approve, I'll be sure to send it along to Zac for further technical review.

Thanks!

@C3POdoo C3POdoo requested review from a team August 2, 2022 19:29
@jcs-odoo jcs-odoo removed the request for review from a team September 5, 2022 13:57
@mivu-odoo mivu-odoo force-pushed the 14.0-social-marketing-added-basic-doc-ksc branch from 08bf8f5 to 991c8dc Compare September 6, 2022 18:24
@mivu-odoo
Copy link
Contributor

As of commit 991c8dc

Fixed the build errors! This PR passes all the code checks now.

  • Removed unexpected indent in create_posts.rst
  • Fixed file path reference in campaigns.rst and push_notifications.rst, it was referencing a file called manage_social but that file didn't exist when I searched the repo. I'm guessing that was the old name for create_posts.rst so I updated the file path references to create_posts

@ksc-odoo
Copy link
Contributor Author

@StraubCreative Ready for your review!

@samueljlieber samueljlieber requested review from StraubCreative and removed request for mivu-odoo February 3, 2023 21:58
Copy link
Contributor

@StraubCreative StraubCreative left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ksc-odoo please update this PR in reference to change requests left on other Marketing PRs as well as the content guidelines. Tag @samueljlieber for help with RST and then tag me again when ready 🙂

@samueljlieber samueljlieber force-pushed the 14.0-social-marketing-added-basic-doc-ksc branch from 991c8dc to db36992 Compare February 15, 2023 19:27
@samueljlieber
Copy link
Contributor

Hey @ksc-odoo 👋 in db36992 I updated the RST content with what you sent over, great job on this BTW!

I did make some structural changes to follow the same structure as the SMS Marketing docs (#2553):

  • instead of having your essentials.rst & campaigns.rst in an overview folder, I changed overview folder to essentials, and moved social_essentials.rst & social_campaigns.rst into that folder.
    • @ksc-odoo what do you think, should we keep the previous overview folder structure?
  • removed push_notifications.rst & livechat.rst to consolidate into social_essentials.rst & social_campaigns.rst
  • added redirects for deleted files

@ksc-odoo ksc-odoo requested a review from StraubCreative March 28, 2023 16:28
@samueljlieber samueljlieber force-pushed the 14.0-social-marketing-added-basic-doc-ksc branch from db36992 to e369e35 Compare March 29, 2023 16:28
@samueljlieber
Copy link
Contributor

Fixed merge conflict in e369e35.

Copy link
Contributor

@StraubCreative StraubCreative left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ksc-odoo can you give these another pass around the following:

  • use of "quotes" and (parenthesis), often times these aren't needed / are distracting.
  • remove all hyperbole/exaggeration language (e.g. utmost importance)
  • specificity of language (e.g. social marketing campaigns help companies connect with the marketplace in uniquely creative
    ways.
    )
  • wordiness...some spots where you can say things more simply/direct and stick to active instruction

Think these just need a final round of love and should be good for merge. Thank you!

@samueljlieber samueljlieber force-pushed the 14.0-social-marketing-added-basic-doc-ksc branch from e369e35 to b7a7556 Compare April 18, 2023 14:38
Copy link
Contributor

@samueljlieber samueljlieber left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @ksc-odoo 👋 I've made your updates in b7a7556 as well as performed my technical review, also making the necessary changes there. My technical changes involved removing :guilable:s from non-action oriented sentences, image size, and leveraging the content tabs block.

Bellow are the suggestions of my changes, already implemented in my previous commit. Please review these changes and let me know if you approve or have any corrections, and I will pass to final review when it is ready. 🙂

Campaigns page
==============

To access a complete overview of all social marketing campaigns, open the :menuselection:`Social
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Make sure to use :menuselection: when directing the user to navigate somewhere

communications can be created, modified, and sent or scheduled. Below is a sample of a completed
campaign template.

.. image:: social_campaigns/create-campaign.png
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This image was a bit too wide at 1600px, make sure the image is below 933px wide - ideally 769px, also make sure the image filename is hyphenated rather than using underscores :)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For sure. I believe the majority of this doc was done awhile back, so there were a few more issues than usual, but I really appreciate you pointing them out/fixing them!

Comment on lines 112 to 120
- :guilabel:`Send New Mailing`: reveals a blank email template on a separate page, in which the
message can be fully customized in a variety of ways.
- :guilabel:`Send SMS`: reveals a blank SMS template on a separate page, in which a SMS
communication can be created and configured.
- :guilabel:`Send Social Post`: reveals a blank social post template on a separate page, in which
a post can be created, and applied to social media accounts that are already connected to the
database.
- :guilabel:`Push Notification`: reveals a similar blank social post template on a separate page,
however, the *Push Notification* options are already pre-selected in the *Post on* field.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No need to add an empty line between bullet points of the same level, this is only necessary when adding a sub-bullet point

Comment on lines 58 to 59
.. note::
Adding social media accounts to the feed also links that specific Social Media's KPIs (if the
platform has them). To get redirected to the statistics and metrics related to any social
account, click on :guilabel:`Insights`.

.. image:: social_essentials/insights.png
:align: center
:alt: The insights link that can be accessed for each social media stream added in Odoo.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I placed this image within the .. note:: block because it seems to be pertaining to that text directly

Comment on lines 224 to 282
.. tabs::

.. tab:: Kanban view

By default, Odoo displays the posts in a *kanban* view. The information on this page can sorted
even further, via the *Filters* and *Group by* drop-down menu.

.. image:: social_essentials/posts-page.png
:align: center
:alt: Kanban view of the posts page in the Odoo Social Marketing application.

.. tab:: Calendar view

The *calendar* view option displays a visual representation in a calendar format of when posts
were published, or are scheduled to be published. This option provides a clear overview of any
planned day, week, or month, and Odoo displays all drafted, scheduled, and published posts.

.. image:: social_essentials/calendar-view.png
:align: center
:alt: Example of the calendar view in Odoo Social Marketing.

.. tab:: List view

The *list* view option is similar to the *kanban* option, but instead of individual blocks,
all the post information is displayed in a clear, list layout. Each line of the list displays
the *Social Accounts*, *Message*, and *Status* of every post.

.. image:: social_essentials/list-view.png
:align: center
:alt: View of the list option on the posts page in Odoo Social Marketing.

.. tab:: Pivot view

The *pivot* view option provides a fully customizable grid table, where different measures of
data can be added and analyzed.

.. image:: social_essentials/pivot-view.png
:align: center
:alt: View of the pivot option on the posts page in Odoo Social Marketing.

The pivot view option provides numerous analytical options, allowing for in-depth, detailed
analysis of various posts.

Click on any :guilabel:`+` (plus sign) next to a line in the pivot table to reveal more metric
options to add to the grid.

While in the pivot view, the option to *Insert in Spreadsheet* is available, located to the
right of the *Measures* drop-down.

When clicked, a pop-up appears, where the option to add this information to a current
spreadsheet is available. The option to create a new spreadsheet for this information
on-the-fly is also available in this pop-up, as well.

Next to the *Insert in Spreadsheet* are three view options, specific to the pivot view.

From left to right, the options are:

- *Flip Axis*, which switches the 'X' and 'Y' axis in the grid table.
- *Expand All*, which expands each line in the grid, revealing more detailed information
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I placed the view option content within content tab blocks here because I think it is a good opportunity to use them to group the related content in an easy-to-compare way. Curious on your thoughts here!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great call!

make any necessary adjustments. Don't forget to hit :guilabel:`Save` to secure any changes.

.. seealso::
:doc:`/applications/marketing/social_marketing/essentials/social_campaigns`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No need to use a bullet point for a single item in a .. seealso::

Copy link
Contributor

@StraubCreative StraubCreative left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@samueljlieber stopping here.

Please clean up the formatting on these docs:

  • italics where there should be guilabels
  • missing guilabels around icons (gear, +, etc.) @ksc-odoo I know you were told different but it's okay if there's disagreement. Imo these are clickable UI objects so they deserve them.
  • italics where there shouldn't be any
  • missing guilabels on dashboard headings
  • capitalizations where there shouldn't be any (e.g. Search bar --> search bar)

Really the only change we've introduced lately is to stop using guilabels on everything, and to only limit it to context around active instruction. I get that there's some confusion and it'll take a few tries (and that's totally fine).

To define this better: active instruction still fulfills a majority of cases, and includes UI walk-throughs where we're looking around the dashboard (because we're still talking about the dashboard that's currently in view).

Comment on lines 5 to 10
Social marketing campaigns help companies connect directly with the marketplace. These campaigns
are vital when introducing a new product to customers, explaining the value of a service/product,
or advertising an upcoming event or product release.

The most effective social marketing campaigns involve multiple channels, so it's important to have
a reliable solution to help with the planning, posting, tracking, and analyzing of content.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: wording/specificity

Suggested change
Social marketing campaigns help companies connect directly with the marketplace. These campaigns
are vital when introducing a new product to customers, explaining the value of a service/product,
or advertising an upcoming event or product release.
The most effective social marketing campaigns involve multiple channels, so it's important to have
a reliable solution to help with the planning, posting, tracking, and analyzing of content.
Social marketing campaigns help companies connect directly with the marketplace. These campaigns
are helpful when introducing a new product to customers, explaining the value of a product or service,
or when advertising an upcoming event or product release.
The most effective social marketing campaigns typically involve multiple channels to maximize
content distribution, and Odoo's *Social Marketing* application acts as a singular control center to
monitor, plan, post, track, and analyze all of the various content and content channels within a
single dashboard.

Comment on lines 23 to 27
Each *stage* in the kanban view can be edited, by clicking the "gear" icon to the left of the "+"
(plus sign) - located to the right of the stage title.

The "gear" icon only appears when the cursor hovers to the left of the "+" (plus sign). When the
"gear" icon is clicked, a drop-down menu reveals the options: *Fold*, *Edit Stage*, and *Delete*.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know there's some uncertainty around guilabel use and icons.
Imo it makes more sense to use them because we're instructing or hinting at the user to click them.
Ideally, I'd love to use emojis here (maybe one day).

Here's what I suggest, with that in mind, and also turning the second sentence into a note:

Suggested change
Each *stage* in the kanban view can be edited, by clicking the "gear" icon to the left of the "+"
(plus sign) - located to the right of the stage title.
The "gear" icon only appears when the cursor hovers to the left of the "+" (plus sign). When the
"gear" icon is clicked, a drop-down menu reveals the options: *Fold*, *Edit Stage*, and *Delete*.
Each *stage* in the kanban view can be edited, by clicking the :guilabel:`gear icon` to the left of
the :guilabel:` + (plus sign icon)` - located to the right of the stage title.
.. note::
The **gear icon** *only* appears when the cursor hovers to the left of the ** + (plus sign
icon)**. When the gear icon is clicked, a drop-down menu reveals the options: :guilabel:`Fold`,
:guilabel:`Edit Stage`, and :guilabel:`Delete`.

Comment on lines 33 to 39
Clicking *Fold* minimizes that specific stage's column. The stage column can be restored by clicking
the folded version of it on the main *Campaigns* page in the default kanban view.

Selecting *Edit Stage* reveals a pop-up, in which the name and the sequence of the stage can be
modified. If changes are made, be sure to click :guilabel:`Save`.

Clicking *Delete* removes the stage entirely.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since we're actively on this dashboard and providing a UI walk-through, these get guilabels.

Suggested change
Clicking *Fold* minimizes that specific stage's column. The stage column can be restored by clicking
the folded version of it on the main *Campaigns* page in the default kanban view.
Selecting *Edit Stage* reveals a pop-up, in which the name and the sequence of the stage can be
modified. If changes are made, be sure to click :guilabel:`Save`.
Clicking *Delete* removes the stage entirely.
Clicking :guilabel:`Fold` minimizes that specific stage's column. The stage column can be restored
by clicking the folded version of it on the main :guilabel:`Campaigns` dashboard in the default
kanban view.
Selecting :guilabel:`Edit Stage` reveals a pop-up window, in which the name and the sequence of the
stage can be modified. If changes are made, be sure to click :guilabel:`Save`.
Clicking :guilabel:`Delete` removes the stage entirely.

cc: @samueljlieber

Comment on lines 41 to 43
.. note::
To add a new stage to the pipeline, side-scroll to the right on the *Campaigns* page, click
:guilabel:`Add a Column`, enter in the desired information, and click :guilabel:`Add`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Campaigns is the dashboard heading that we're currently on, so it gets a guilabel.

Suggested change
.. note::
To add a new stage to the pipeline, side-scroll to the right on the *Campaigns* page, click
:guilabel:`Add a Column`, enter in the desired information, and click :guilabel:`Add`.
.. note::
To add a new stage to the pipeline, side-scroll to the right on the :guilabel:`Campaigns`
dashboard, click :guilabel:`Add a Column`, enter in the desired information, and click
:guilabel:`Add`.

@samueljlieber samueljlieber force-pushed the 14.0-social-marketing-added-basic-doc-ksc branch 2 times, most recently from e7d06a6 to bdbc3a4 Compare April 20, 2023 15:47
@samueljlieber
Copy link
Contributor

samueljlieber commented Apr 20, 2023

Hi @StraubCreative, thank you for your corrections here. I've gone through social_essentials.rst and social_campaigns.rst and implemented your corrections in bdbc3a4.

I would like to note that the docs KC initially provided me had many of your suggestions correct already - I ended up swapping most to Italics in my technical changes. I think my confusion stems from how the active instruction is written in these docs. To me, it isn't as direct as other writing styles (which I have no qualms about, its just different in a good way 🙂). For example:

This:

The same social marketing campaign information on the :guilabel:`Campaigns` dashboard can also be viewed as a list, by selecting the :guilabel:`List` option, located under the search bar, in the upper-right corner.

Is not as direct as this:

To view the social marketing campaign information as a list on the :guilabel:`Campaigns` dashboard, select the :guilabel:`List` option, located under the search bar, in the upper-right corner.

So by comparing these two, it is now clear to me that the :guilabel: is valid in both writing styles.

I feel this PR is ready for another look when you are ready @StraubCreative, thank you! 🙏

C.C. @ksc-odoo

Copy link
Contributor

@StraubCreative StraubCreative left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @ksc-odoo

Made a batch of edits in the commit following this review, mostly around guilabel/italics use (I know it's annoying/confusing!), and some wording and formatting suggestions.

Please let me know if you approve of the changes or If you have any disagreements, thanks!

Comment on lines 62 to 64
On the :guilabel:`Campaigns` dashboard, a new campaign can be created by clicking the quick add **+
plus sign** - located at the top-right of each stage in the pipeline, visible in the kanban view.
Or, by clicking :guilabel:`Create` in the upper-left corner of the :guilabel:`Campaigns` dashboard.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

guilabel on the + icon
starting a new sentence with a conjunction reads a little strange 😛

Suggested change
On the :guilabel:`Campaigns` dashboard, a new campaign can be created by clicking the quick add **+
plus sign** - located at the top-right of each stage in the pipeline, visible in the kanban view.
Or, by clicking :guilabel:`Create` in the upper-left corner of the :guilabel:`Campaigns` dashboard.
On the :guilabel:`Campaigns` dashboard, a new campaign can be created by clicking the quick add
:guilabel:`+ (plus sign)` located in the top-right corner of each stage in the pipeline, visible in
the kanban view. Campaigns can also be created by clicking :guilabel:`Create` in the upper-left
corner of the :guilabel:`Campaigns` dashboard.

:align: center
:alt: View of the quick add option for campaigns in Odoo Social Marketing.

Here, a :guilabel:`Campaign Name`, :guilabel:`Responsible`, and :guilabel:`Tags` can be entered.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

grammar

Suggested change
Here, a :guilabel:`Campaign Name`, :guilabel:`Responsible`, and :guilabel:`Tags` can be entered.
Here, the :guilabel:`Campaign Name`, :guilabel:`Responsible`, and :guilabel:`Tags` can be entered.

Comment on lines 87 to 88
- On the :guilabel:`Campaigns` dashboard in the kanban view, select the **three dot** drop-down menu
on the desired campaign, and select :guilabel:`Edit`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Use three-dots text icon and add a guilabel

Suggested change
- On the :guilabel:`Campaigns` dashboard in the kanban view, select the **three dot** drop-down menu
on the desired campaign, and select :guilabel:`Edit`.
- On the :guilabel:`Campaigns` dashboard in the kanban view, select the :guilabel:`⋮ (three dots)`
drop-down menu on the desired campaign, and select :guilabel:`Edit`.

Comment on lines +95 to +98
On a *Campaign Template* page, numerous elements can be customized/modified, and various forms of
communications can be created, modified, and sent or scheduled. Below is a sample of a completed
campaign template.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Images are only supplemental to the text.
In a future PR let's write all of this out 👍

Comment on lines 103 to 107
.. important::
In order for the :guilabel:`Send New Mailing` option to appear on campaign templates, make sure
the :guilabel:`Mailing Campaigns` feature is enabled in the *Email Marketing* app. To do that,
navigate to :menuselection:`Email Marketing --> Configuration --> Settings`, activate
:guilabel:`Mailing Campaigns`, and click :guilabel:`Save`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The first instance of mailing campaigns here gets an italics since it's a feature being emphasized.
We're not looking at that dashboard (yet), and we're emphasizing it as part of a logic.

Suggested change
.. important::
In order for the :guilabel:`Send New Mailing` option to appear on campaign templates, make sure
the :guilabel:`Mailing Campaigns` feature is enabled in the *Email Marketing* app. To do that,
navigate to :menuselection:`Email Marketing --> Configuration --> Settings`, activate
:guilabel:`Mailing Campaigns`, and click :guilabel:`Save`.
.. important::
In order for the :guilabel:`Send New Mailing` option to appear on campaign templates, make sure
the *Mailing Campaigns* feature is enabled in the *Email Marketing* app. To do that, navigate to
:menuselection:`Email Marketing --> Configuration --> Settings`, activate :guilabel:`Mailing
Campaigns`, and click :guilabel:`Save`.

Comment on lines 215 to 216
'Posts' page
============
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apostrophes aren't needed?

Suggested change
'Posts' page
============
Posts page
==========

Comment on lines 269 to 270
Click on any **+ (plus sign)** next to a line in the pivot table to reveal more metric options
to add to the grid.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Click on any **+ (plus sign)** next to a line in the pivot table to reveal more metric options
to add to the grid.
Click on any :guilabel:`+ (plus sign) icon` next to a line in the pivot table to reveal more metric
options to add to the grid.


From left to right, the options are:

- :guilabel:`Flip Axis`, which switches the 'X' and 'Y' axis in the grid table.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- :guilabel:`Flip Axis`, which switches the 'X' and 'Y' axis in the grid table.
- :guilabel:`Flip Axis`, which switches the *X* and *Y* axis in the grid table.

========

To see a complete overview of all the people who have visited the website(s) connected to the
database, click :menuselection:`Visitors` in the header menu of the *Social Marketing* app.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Force the tag

Suggested change
database, click :menuselection:`Visitors` in the header menu of the *Social Marketing* app.
database, navigate to :menuselection:`Social Marketing --> Visitors` in the header menu.

Comment on lines 339 to 341
Navigate to :menuselection:`Configuration --> Social Streams` reveals a separate page containing all
the social media streams that have been added to the main dashboard of the *Social Marketing* app,
accessible via the :guilabel:`Feed` option in the header menu.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Grammar

Suggested change
Navigate to :menuselection:`Configuration --> Social Streams` reveals a separate page containing all
the social media streams that have been added to the main dashboard of the *Social Marketing* app,
accessible via the :guilabel:`Feed` option in the header menu.
Navigate to :menuselection:`Configuration --> Social Streams` to reveal a separate page containing
all of the social media streams that have been added to the main dashboard of the *Social Marketing*
app, accessible via the :guilabel:`Feed` option in the header menu.

@StraubCreative StraubCreative force-pushed the 14.0-social-marketing-added-basic-doc-ksc branch from bdbc3a4 to dbcc72b Compare April 21, 2023 00:41
Copy link
Contributor

@StraubCreative StraubCreative left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

repeat designation for PRs worth a second look

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants