F21 Beats are Open!

Pete Travis me at petetravis.com
Thu Apr 17 19:08:43 UTC 2014

Greetings Writers,

The Release Note Beats[0] are open for Fedora 21!  I'm slow in sending out
this notice, actually, they've been clear for a while, but it is time to
get together and get each other motivated to write.

If you're new to Docs, Beat writing is a good way to get started. Simply
choose a package, service, or functionality that interests you and do a
little research to see how will change in F21.  You can check rawhide
package changelogs[1], read the software changelogs in
/usr/share/doc/$pkgname, scrape upstream mailing lists and commit logs, and
reach out to package maintainers or developers.

Of course, this is a broadly defined task, and intimidating for even
experienced writers. Fedora is a big project, there's a lot going on!
Remember that it's a cooperative endeavor, you don't have to do it alone.
You can reach out to a mentor[2], mail the list[3], or hang out in
#fedora-docs (especially during Office Hours[4]).

Remember that the categories are a guideline. It can be hard to fit
information into one, but it can all be sorted out later on.  Taking
ownership of a whole beat is great, and adding content for various beats as
you learn about changes is great too. It's better to have two perspectives
on one feature than to have none shared because the writers didn't want to
step on each others' toes.

For a given feature, I like to highlight a few things:
- Briefly explain the software and its purpose.  That might only mean a
simple sentence fragment, like "The popular http server Apache...".   Other
software might be more complex and require more explanation.  The reader
doesn't always know what the software is, so explain a little.
- Elaborate on how to use the new feature.  For command line utilities,
this could be example invocations and some context on when or why  one
would use the cited command. For complex features, you could briefly
explain the use case and refer to upstream documentation.  Avoid
demonstrations that require screenshots - images don't translate well.
- Provide references to upstream documentation, upstream release notes,
relevant Fedora Documentation, and other useful resources.
- If the feature affects one of our guides, speak up! Let the guide
maintainer know with a mail or bug report.

The last and possibly most helpful way you can contribute to the Release
Notes is to talk about the beats process.  Discussion can help other beats
writers feel engaged instead of isolated.  If you interact with other areas
of Fedora, talk to those groups about Beats.  Many people each making small
contributions, noting a single change, will produce a much more
comprehensive work than a dedicated few could ever manage.

Thanks for reading, and for writing!

[0] https://fedoraproject.org/wiki/Category:Documentation_beats
[1] http://pkgs.fedoraproject.org/cgit/ - find the package, browse the
source tree for $pkgname.spec. The changelog is at the bottom.
[2] https://fedoraproject.org/wiki/Docs_Project_mentors
[3] https://admin.fedoraproject.org/mailman/listinfo/docs
[4] Currently 1800UTC Thursdays and 1500UTC Sundays
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.fedoraproject.org/pipermail/docs/attachments/20140417/751a6ef2/attachment.html>

More information about the docs mailing list