Skip to content

Expand plain language documentation with best practices#127

Open
huda-code wants to merge 1 commit into
DSACMS:mainfrom
huda-code:patch-1
Open

Expand plain language documentation with best practices#127
huda-code wants to merge 1 commit into
DSACMS:mainfrom
huda-code:patch-1

Conversation

@huda-code

Copy link
Copy Markdown

Added sections on the importance of plain language, best practices, and federal resources to enhance understanding and usability.

module-name: One line description of your change (less than 72 characters)

Problem

Explain the context and why you're making that change. What is the problem
you're trying to solve? In some cases there is not a problem and this can be
thought of being the motivation for your change.

Solution

Describe the modifications you've done.

Result

What will change as a result of your pull request? Note that sometimes this
section is unnecessary because it is self-explanatory based on the solution.

Some important notes regarding the summary line:

  • Describe what was done; not the result
  • Use the active voice
  • Use the present tense
  • Capitalize properly
  • Do not end in a period — this is a title/subject
  • Prefix the subject with its scope

Test Plan

(Write your test plan here. If you changed any code, please provide us with
clear instructions on how you verified your changes work.)

Added sections on the importance of plain language, best practices, and federal resources to enhance understanding and usability.

@natalialuzuriaga natalialuzuriaga left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Hi @huda-code,

Thank you so much for this valuable contribution to our ospo-guide. We've been meaning to update our plain language guide so this work is so appreciated.

A couple of things before we ship this guide:

  1. For documentation, please fill out the PR template with information about the Problem, Solution, and Result. Note that this PR address this issue: #32
  2. I flagged changes in markdown file to be addressed

Thank you!

Comment on lines +48 to +51
## Federal Resources
* PlainLanguage.gov
* Federal Plain Language Guidelines
* Digital.gov Plain Language Web Writing Tips

@natalialuzuriaga natalialuzuriaga Jun 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Currently, these websites are plain text. Could you add them as links to these resources so it would be helpful for users to check out

* Digital.gov Plain Language Web Writing Tips

## Additional Reading
Digital.gov provides practical guidance for creating web content that is concise, accessible, and user-centered. Their recommendations emphasize audience-focused writing, scannable content, and clear calls to action.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Please make "digital.gov" a link to the digital.gov plain language guide

title: Plain Language
sidenav: true
sticky_sidenav: true
---

@natalialuzuriaga natalialuzuriaga Jun 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Lines 1-15 are deleted but this is front matter needed for the website so it displays successfully at https://dsacms.github.io/ospo-guide/growing/plain-language/. Please return this!

@natalialuzuriaga natalialuzuriaga added documentation Improvements or additions to documentation enhancement New feature or request labels Jun 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants