User:Laubersm/Documentation User Guide Update Checklist

From FedoraProject

< User:Laubersm(Difference between revisions)
Jump to: navigation, search
(F14 Status table)
(Reset Status table for F15)
 
(19 intermediate revisions by 2 users not shown)
Line 12: Line 12:
 
*Things to consider during the review - you don't have to do all of it - team up with someone if your strength is technical fact checking and you need help with the wordsmithing! (or the other way around).
 
*Things to consider during the review - you don't have to do all of it - team up with someone if your strength is technical fact checking and you need help with the wordsmithing! (or the other way around).
  
;(Re)write Chapter: This stage is for two things: re-fact checking and then editing the formatting and organization of sections so that it lines up with all of our conventions.  This could mean anything from fixing headers to putting in admons (like the ones at the bottom of this page) to making sure that the standard installation process is referenced instead of including it inline. Ideally most rewriting is done between releases (from release to next alpha).
+
;(Re)write Chapter: This stage is for two things: re-fact checking and then editing the formatting and organization of sections so that it lines up with all of our conventions.  This could mean anything from fixing headers to putting in admons (like the ones at the bottom of this page) to making sure that the standard installation process is referenced instead of including it inline. <p> Ideally most rewriting is done between releases (from release to next alpha). There should also be a bugzilla number to track the progress of each idea/request including getting reviews from other teams on technical accuracy. Bugs also help alert new contributors of an opportunity to jump in.</p>
  
;Fact Check: This stage just changes all factual information so that it syncs up with the facts for the upcoming version.  If the default browser happens to be Dillo instead of Firefox for this release, the Fact Check stage should reflect this after completion. This is the core of the work during Alpha and with the early release candidates for Beta.
+
;Fact Check: This stage just changes all factual information so that it syncs up with the facts for the upcoming version.  If the default browser happens to be Dillo instead of Firefox for this release, the Fact Check stage should reflect this after completion. This is the core of the work during Alpha and with the early release candidates for Beta. <p> This stage is most commonly tracked in the wiki table. This allows fast updates of what is done and needs to be done when many eyes are working together and does not clutter bugzilla with "see if anything needs to change" bugs. </p>
  
 
;Edit/Wordsmith: This is for the English majors.  Make the page grammatically sound while keeping our conventions and a technical writing style in mind.  Extra points go for stylizing the writing as long as it doesn't conflict with the core goals of readability and simplicity in comprehension.  
 
;Edit/Wordsmith: This is for the English majors.  Make the page grammatically sound while keeping our conventions and a technical writing style in mind.  Extra points go for stylizing the writing as long as it doesn't conflict with the core goals of readability and simplicity in comprehension.  
Line 34: Line 34:
  
  
===F14 Status table===
+
===F15 Status table===
 +
F14 has been branched for translation.  Only drastic "it is really wrong" bug fixes should be applied.  All other update should be applied to the master branch for "Next Release"
  
 +
<!-- Fact checking during alpha instructions:
 
* When you claim a chapter to review, place your name in the column.
 
* When you claim a chapter to review, place your name in the column.
 
* As you take breaks, update the status.  This way someone else can pick it up if you cannot get back to it.  This is also a where you can indicate that you need some help in the review such as wordsmithing or fixing an xml error.
 
* As you take breaks, update the status.  This way someone else can pick it up if you cannot get back to it.  This is also a where you can indicate that you need some help in the review such as wordsmithing or fixing an xml error.
 
* When the review is complete, note that it is ready for translation
 
* When the review is complete, note that it is ready for translation
 +
-->
 +
* Please sign your comments
  
 
{|
 
{|
 
|-
 
|-
| Chapter || I'll do it! || Status (in progress, fact checking done, needs wordsmithing,etc) || Ready for translation?
+
| Chapter || Rework suggestions (include bugzilla number) || Alpha fact checking status (in progress, fact checking done, needs wordsmithing,etc) || Ready for translation?
 
|-
 
|-
| Introduction  || [[User:Laubersm|Laubersm]] || Fact Checking done [[User:Laubersm|Laubersm]] 21:00, 14 October 2010 (UTC) || Y
+
| Introduction  || || || N
 
|-
 
|-
| The Fedora Desktops  || || Fact Checking done [[User:Laubersm|Laubersm]] 21:00, 14 October 2010 (UTC) || Y
+
| The Fedora Desktops  || || ||  
 
|-
 
|-
| Logging into the Desktop || || Fact Checking done [[User:Laubersm|Laubersm]] 01:09, 15 October 2010 (UTC) || Y
+
| Logging into the Desktop || || ||  
 
|-
 
|-
| Tour of the GNOME Desktop || ||Fact Checking done [[User:Laubersm|Laubersm]] 01:44, 15 October 2010 (UTC)|| Y
+
| Tour of the GNOME Desktop || || ||  
 
|-
 
|-
| Tour of the KDE Desktop ||  || Fact checking done [[User:bcotton|bcotton]] 23 Oct 2010 || Y
+
| Tour of the KDE Desktop ||  || ||  
 
|-
 
|-
| Tour of the Xfce Desktop || ||  Fact checking done [[User:bcotton|bcotton]] 23 Oct 2010 || Y
+
| Tour of the Xfce Desktop || ||  ||  
 
|-
 
|-
| Media (Media.xml) || [[User:Laubersm|Laubersm]] || Need to fact '''check KDE''' references. GNOME (and general) done. Also '''check min size''' for liveusb media stick and liveDVD images instead of LiveCD are tight is not impossible on 1G ||  
+
| Media (Media.xml) || Check live-usb requirements (currently 1G) || ||
 
|-
 
|-
| Connecting to the Internet (Connecting_to_the_Internet.xml) || || fact check done [[User:Laubersm|Laubersm]] 15:58, 15 October 2010 (UTC) || Y
+
| Connecting to the Internet (Connecting_to_the_Internet.xml) || || ||  
 
|-
 
|-
| Accessing the Web || || fact checking done [[User:Laubersm|Laubersm]] 02:18, 21 October 2010 (UTC) || Y
+
| Accessing the Web || || ||  
 
|-
 
|-
| Communications (Communications.xml) || || ||  
+
| Communications (Communications.xml) || || ||  
 
|-
 
|-
| Printing (Printing.xml) || || new chapter - location still to be confirmed. Does not have Xfce section yet [[User:bcotton|bcotton]] will add for F15 ||
+
| Printing (Printing.xml) || Does not have Xfce section yet [[User:bcotton|bcotton]] will add for F15 || ||  
 
|-
 
|-
| Office Applications || || ||  
+
| Office Applications || || ||  
 
|-
 
|-
| Financial Software || || ||  
+
| Financial Software || || ||
 
|-
 
|-
| Playing Multimedia (Playing_multimedia.xml) || || Check [https://bugzilla.redhat.com/show_bug.cgi?id=588582 BUG 588582] ||  
+
| Playing Multimedia (Playing_multimedia.xml) || || ||  
 
|-
 
|-
| Playing games || || fact check done [[User:Laubersm|Laubersm]] 02:00, 22 October 2010 (UTC) || Y
+
| Playing games || || ||  
 
|-
 
|-
 
| Managing photos || || ||  
 
| Managing photos || || ||  
 
|-
 
|-
| Sharing your desktop ||  || Fact check done [[User:bcotton|bcotton]] 1747 25 October 2010 (UTC) || Y
+
| Sharing your desktop ||  || ||  
 
|-
 
|-
| Customizing the desktop || [[User:bcotton|bcotton]] || ||  
+
| Customizing the desktop || May want to add new input methods mentioned in the F14 release notes [[User:Laubersm|Laubersm]] || ||
 
|-
 
|-
| Managing software || [[User:Laubersm|Laubersm]] || ||  
+
| Managing software || really needs more kpackage stuff and some streamlining of the yum to remove duplicate examples [[User:Laubersm|Laubersm]] || ||  
 
|-
 
|-
| Contributors and Revision History || [[User:Laubersm|Laubersm]] || Link to current version translator list doesn't seem to have an F14 version in wiki || no
+
| Contributors and Revision History || add translators for F14 to list along with F15 editors/writers || || No
 
|}
 
|}
  
 
===Other general todo items for UG===
 
===Other general todo items for UG===
* Add chapter on printing https://bugzilla.redhat.com/show_bug.cgi?id=508025 - Thanks bcotton!
+
* <strike>Add chapter on printing https://bugzilla.redhat.com/show_bug.cgi?id=508025</strike> - Thanks bcotton!
  
 
* Integrate Matthew's updates for
 
* Integrate Matthew's updates for
 
** Finding Software -  
 
** Finding Software -  
  
* Update screen shots (desktops) as needed
+
* <strike>Update screen shots (desktops) as needed</strike> done by bcotton
* Update Revision History, Book Info, and ent for version 14  
+
* <strike>Update Revision History, Book Info, and ent for version 14 </strike> done [[User:Laubersm|Laubersm]] 20:34, 26 October 2010 (UTC)
* verify all authors are added to Contributors_and_production_methods.xml and Revision_History.xml
+
* <strike>verify all authors and f13 translators are added to Contributors_and_production_methods.xml and Revision_History.xml</strike> [[User:Laubersm|Laubersm]] 19:53, 28 October 2010 (UTC)
  
 
==General LifeCycle of the User Guide==
 
==General LifeCycle of the User Guide==
Line 137: Line 141:
 
*Figure out Trac.  https://fedorahosted.org/userguide/ looks like it was used briefly with F9 wiki -> xml conversion and that is all.  Start with can I edit main page or how to I gain access to edit main page.
 
*Figure out Trac.  https://fedorahosted.org/userguide/ looks like it was used briefly with F9 wiki -> xml conversion and that is all.  Start with can I edit main page or how to I gain access to edit main page.
 
*Create wiki page with procedures and general task lists for managing the user guide.  Point to trac and bugzilla and git.
 
*Create wiki page with procedures and general task lists for managing the user guide.  Point to trac and bugzilla and git.
 +
*Branch instructions are at: https://fedoraproject.org/wiki/Branching_a_document_in_git
 +
*Publishing instructions are at: https://fedoraproject.org/wiki/Publishing_a_document_with_Publican

Latest revision as of 15:12, 29 October 2010

Contents

[edit] How to do the reviews

[edit] Need F14 box (Virtual Machine is fine for most chapters)

  • Use most current release candidate
  • The style guide is located....
  • Things to consider during the review - you don't have to do all of it - team up with someone if your strength is technical fact checking and you need help with the wordsmithing! (or the other way around).
(Re)write Chapter
This stage is for two things: re-fact checking and then editing the formatting and organization of sections so that it lines up with all of our conventions. This could mean anything from fixing headers to putting in admons (like the ones at the bottom of this page) to making sure that the standard installation process is referenced instead of including it inline.

Ideally most rewriting is done between releases (from release to next alpha). There should also be a bugzilla number to track the progress of each idea/request including getting reviews from other teams on technical accuracy. Bugs also help alert new contributors of an opportunity to jump in.

Fact Check
This stage just changes all factual information so that it syncs up with the facts for the upcoming version. If the default browser happens to be Dillo instead of Firefox for this release, the Fact Check stage should reflect this after completion. This is the core of the work during Alpha and with the early release candidates for Beta.

This stage is most commonly tracked in the wiki table. This allows fast updates of what is done and needs to be done when many eyes are working together and does not clutter bugzilla with "see if anything needs to change" bugs.

Edit/Wordsmith
This is for the English majors. Make the page grammatically sound while keeping our conventions and a technical writing style in mind. Extra points go for stylizing the writing as long as it doesn't conflict with the core goals of readability and simplicity in comprehension.
Edit Format/XML Conversion
Make sure it still builds in Publican! This task continues through Beta with any updates as well as ensuring that the translated versions also build without error.

[edit] Submitting updates

  • All edits get done in xml/docbook/git (master branch)
    • If you do not have commit access, please submit a git formatted patch to the docs mailing list or in bugzilla
    • git diff > mypatch-chaptername
    • Then attach mypatch-chaptername
  • If you submit enough, do not be surprised if you are given commit access.
  • If you cannot provide a git formatted patch, do not let that stop you, submit suggestions, paragraphs, fixes, anyway possible.


[edit] F15 Status table

F14 has been branched for translation. Only drastic "it is really wrong" bug fixes should be applied. All other update should be applied to the master branch for "Next Release"

  • Please sign your comments
Chapter Rework suggestions (include bugzilla number) Alpha fact checking status (in progress, fact checking done, needs wordsmithing,etc) Ready for translation?
Introduction N
The Fedora Desktops
Logging into the Desktop
Tour of the GNOME Desktop
Tour of the KDE Desktop
Tour of the Xfce Desktop
Media (Media.xml) Check live-usb requirements (currently 1G)
Connecting to the Internet (Connecting_to_the_Internet.xml)
Accessing the Web
Communications (Communications.xml)
Printing (Printing.xml) Does not have Xfce section yet bcotton will add for F15
Office Applications
Financial Software
Playing Multimedia (Playing_multimedia.xml)
Playing games
Managing photos
Sharing your desktop
Customizing the desktop May want to add new input methods mentioned in the F14 release notes Laubersm
Managing software really needs more kpackage stuff and some streamlining of the yum to remove duplicate examples Laubersm
Contributors and Revision History add translators for F14 to list along with F15 editors/writers No

[edit] Other general todo items for UG

  • Integrate Matthew's updates for
    • Finding Software -
  • Update screen shots (desktops) as needed done by bcotton
  • Update Revision History, Book Info, and ent for version 14 done Laubersm 20:34, 26 October 2010 (UTC)
  • verify all authors and f13 translators are added to Contributors_and_production_methods.xml and Revision_History.xml Laubersm 19:53, 28 October 2010 (UTC)

[edit] General LifeCycle of the User Guide

[edit] During Alpha

  • All new features should be announced and included in the alpha. This is the time to review the User Guide for major changes such as new default applications or major look and feel changes to GNOME, KDE, or other desktops covered.

[edit] During Beta

  • Complete the review of all chapters and branch for translation. Since the UG should not change much beyond beta, this document should be branched early in the beta cycle so that translators can get the work done and be ready for the push of more significant document updates such as the installation guide and release notes.
  • Builds of draft documentation in the languages occurs during this time. Review the builds for xml errors and review bugzilla for content fixes to be made. Correct what is wrong but balance that with minimizing changes that will cause more work for the translation teams.

[edit] After Release

  • regularly review bugzilla, update master branch, and close bugs as "next release".
  • This is the time to do any major rework for the next version. This includes new chapters or major reorganization.

[edit] Notes to Contributors

[edit] Application Installations

Whenever we discuss an application not installed by default, we should put a note about having to install it. The note should look like this:

Of course, this should be edited according to the application name, package name, and application home page, but try to use this template for consistency's sake.

  • Also note that I just made this convention up, so don't feel like you should have known this before. If you have suggestions or comments, let me know.

--Danielsmw 15:08, 25 February 2009 (UTC)

[edit] Advanced Topics

Whenever we add something that would be nice to have in the user's guide but isn't necessary for the basic desktop user who just migrated fresh from Windows (example: discussion of FTP programs, advanced discussion of yum on the command line), we should add a template to let the confused user know not to worry about this section if they don't want to. This is what I've come up with right now:

Important.png
Advanced Usage
This content is written for the more advanced user. It assumes that you are comfortable with the command line and have a relatively good knowledge of Linux terminology. It is probably not necessary to using Fedora as a desktop user, but can help a desktop user expand his or her knowledge base and face more complicated troubleshooting issues.

That, again, is just my current idea until someone suggests or comments on that. Let me know in IRC or on the list. --Danielsmw 15:08, 25 February 2009 (UTC)

[edit] admin tasks TODO