User:Laubersm/Documentation User Guide Update Checklist

From FedoraProject

< User:Laubersm(Difference between revisions)
Jump to: navigation, search
(update status)
(Prep for F14)
Line 1: Line 1:
==April 22-26 items:==
+
==General LifeCycle of the User Guide==
 +
===During Alpha===
  
* KDE is with alpha background... should be updated once more.
+
* 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.  
  
* Add chapter on printing https://bugzilla.redhat.com/show_bug.cgi?id=508025 - Unless there is a volunteer, will be left for F14.
+
* update and/or close bugs: https://bugzilla.redhat.com/buglist.cgi?query_format=advanced&bug_status=NEW&bug_status=ASSIGNED&bug_status=MODIFIED&bug_status=ON_DEV&bug_status=ON_QA&bug_status=VERIFIED&bug_status=RELEASE_PENDING&component=user-guide&product=Fedora%20Documentation&classification=Fedora
 +
 
 +
===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.
  
 
* update and/or close bugs: https://bugzilla.redhat.com/buglist.cgi?query_format=advanced&bug_status=NEW&bug_status=ASSIGNED&bug_status=MODIFIED&bug_status=ON_DEV&bug_status=ON_QA&bug_status=VERIFIED&bug_status=RELEASE_PENDING&component=user-guide&product=Fedora%20Documentation&classification=Fedora
 
* update and/or close bugs: https://bugzilla.redhat.com/buglist.cgi?query_format=advanced&bug_status=NEW&bug_status=ASSIGNED&bug_status=MODIFIED&bug_status=ON_DEV&bug_status=ON_QA&bug_status=VERIFIED&bug_status=RELEASE_PENDING&component=user-guide&product=Fedora%20Documentation&classification=Fedora
  
== admin tasks TODO ==
+
===After Release===
*Find out where git commits are going -  ie not to someplace I am already subscribed to
+
*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.
+
  
==What you need ==
+
* regularly review bugzilla, update master branch, and close bugs as "next release".
=== Need F13 box (Virtual Machine is fine) ===
+
Beta with updates
+
  
Use most current release candidate
+
* This is the time to do any major rework for the next version.  This includes new chapters or major reorganization.
  
Current RC testing progress and howto at https://fedoraproject.org/wiki/Test_Results:Current_Installation_Test
+
* update and/or close bugs: https://bugzilla.redhat.com/buglist.cgi?query_format=advanced&bug_status=NEW&bug_status=ASSIGNED&bug_status=MODIFIED&bug_status=ON_DEV&bug_status=ON_QA&bug_status=VERIFIED&bug_status=RELEASE_PENDING&component=user-guide&product=Fedora%20Documentation&classification=Fedora
  
It may also be useful to keep an eye on https://fedoraproject.org/wiki/Common_F13_bugs
+
==How to do the reviews==
 +
=== Need F14 box (Virtual Machine is fine for most chapters) ===
  
===submitting updates===
+
*Use most current release candidate
All edits should be 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
+
*Current RC testing progress and howto at https://fedoraproject.org/wiki/Test_Results:Current_Installation_Test
  
git diff > mypatch-chaptername
+
*It may also be useful to keep an eye on https://fedoraproject.org/wiki/Common_F14_bugs
  
Then attach mypatch-chaptername
+
*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).
  
If you submit enough, do not be surprised if you are given commit access.
+
;(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).
  
If you cannot provide a git formatted patch, do not let that stop you, submit suggestions, paragraphs, fixes, anyway possible.
+
;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.
  
 +
;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.
  
==Already Done List==
+
;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.
* <strike>Update Revision History, Book Info, and ent for version 13 - done</strike>
+
  
* Add in paragraph on changing language input methods https://bugzilla.redhat.com/show_bug.cgi?id=514641
+
===Submitting updates===
** <strike>Adding to customizing the desktop</strike> - done, proofreading welcome [[User:Laubersm|Laubersm]] 22:13, 31 March 2010 (UTC)
+
*All edits get done in xml/docbook/git (master branch)
** <strike>Also check 2.1 Logging In - isn't there a language option on gdm (default) and kdm in addition to desktop optional selection?</strike> There is and reference as been added  [[User:Laubersm|Laubersm]] 20:24, 31 March 2010 (UTC)
+
  
* <strike>Check 2.3</strike> - is there a default limit of failed logins before lock out? Common in Enterprisebut I do not think it is set up in Fedora default install. -- There is no mention of it in gdm.schemas [[User:Nathant|Nathant]]
+
**If you do not have commit access, please submit a git formatted patch to the docs mailing list or in bugzilla
  
* Integrate Matthew's updates for
+
**git diff > mypatch-chaptername
** <strike>Intro</strike> - done, proofreading still welcome.  [[User:Laubersm|Laubersm]]
+
** <strike>Finding Software</strike> - leave Matthew's for F14.  Did complete a proof reading of chapter for F13 [[User:Laubersm|Laubersm]]
+
** Office Suites - '''Pull out ALL and hold for after Beta Release'''
+
*** Matthew's comments added,
+
*** other sections revised or commented out for additional rework [[User:Laubersm|Laubersm]] 02:04, 1 April 2010 (UTC)
+
  
* Proof read all "Tour of <desktop>" chapters for accuracy with F13 - check version numbers, apps mentioned still exist and as described)
+
**Then attach mypatch-chaptername
** <strike>GNOME</strike> - patch submitted to mailing list [[User:lewis41|luigi votta]], applied by [[User:Laubersm|Laubersm]] 16:08, 31 March 2010 (UTC), additional reveiw [[User:Laubersm|Laubersm]] 18:33, 31 March 2010 (UTC) Still needs image updates (separate list item)
+
** <s>KDE -- rlandmann</s> - done [[User:Rlandmann|Rlandmann]] 14:24, 9 April 2010 (UTC)
+
** <strike>Xfce</strike> - done [[User:Laubersm|Laubersm]] 19:47, 31 March 2010 (UTC)
+
  
* Proof read all other chapters for accuracy with F13 (app name, menu name and location, major features, etc)
+
*If you submit enough, do not be surprised if you are given commit access.
** <strike>media (burning cd/dvd)</strike> - done [[User:Laubersm|Laubersm]] 21:08, 1 April 2010 (UTC)
+
** <strike>accessing the web (firefox and konquer and ftp)</strike> - [[User:Laubersm|Laubersm]] 02:59, 1 April 2010 (UTC)
+
** <strike>communications (thunderbird and evolution)</strike> - done [[User:Laubersm|Laubersm]] 21:35, 8 April 2010 (UTC)
+
** <strike>Financial</strike>  - --[[User:Ke4qqq|ke4qqq]] 12:11, 1 April 2010 (UTC)
+
** <strike>Multimedia (music, video)</strike> - stickster said he was done (see docs meeting log)
+
** <strike>Games</strike> - done, proofreading welcome. [[User:Laubersm|Laubersm]] 15:47, 31 March 2010 (UTC)
+
** <strike>Photos</strike> -- done, proofreading welcome [[User:Nathant|NathanT]]
+
** <strike>Sharing the Desktop</strike> -- done [[User:ke4qqq|ke4qqq]]
+
** <strike>Customize the desktop</strike> - adding changing input methods here - done [[User:Laubersm|Laubersm]] 22:13, 31 March 2010 (UTC)
+
  
* redo Connecting to the Internet for F13 -
+
*If you cannot provide a git formatted patch, do not let that stop you, submit suggestions, paragraphs, fixes, anyway possible.
** <strike>draft submitted to list by [[User:lewis41|luigiv]]
+
** draft submitted in wiki by [[User:lewis41|luigiv]]; Connecting_to_the_Internet: xml on [http://lewis41.fedorapeople.org lewis41.fedorapeople] and [[User:Lewis41/NetworkManager_f13 | Wiki: NetworkManager_f13]]</strike>
+
** draft converted into master branch, re-ordered, and edited. [[User:Laubersm|Laubersm]] 02:59, 22 April 2010 (UTC)
+
** final proofreading still a good idea!
+
  
* Office Suites -
 
** <strike>Matthew's comments added, </strike>
 
** <strike>other sections revised or commented out for additional rework</strike>
 
** rewrite pushed to master. [[User:Laubersm|Laubersm]] 02:59, 22 April 2010 (UTC)
 
** final proofreading would be a good idea
 
  
* Update images of desktops to F13 (verify final artwork for background first!) -
+
===F14 Status table===
** updated background rpms are available in yum.
+
** need instructions on size, resolutions, alpha channel, etc : http://jfearn.fedorapeople.org/en-US/Publican/1.5/html/Users_Guide/chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Adding_images
+
** gnome done, xfce done
+
** KDE is with alpha background... should be updated once more.
+
  
 +
* When you claim a chapter to review, place your name in the column.
 +
* When the review is complete, update the status.
 +
 +
 +
 +
* Add chapter on printing https://bugzilla.redhat.com/show_bug.cgi?id=508025 - Unless there is a volunteer, will be left for F14.
 +
 +
* Integrate Matthew's updates for
 +
** Finding Software -
 +
 +
* Update screen shots (desktops) as needed
 +
* Update Revision History, Book Info, and ent for version 14
 
* verify all authors are added to Contributors_and_production_methods.xml and Revision_History.xml
 
* verify all authors are added to Contributors_and_production_methods.xml and Revision_History.xml
  
* Verify paragraph on changing language input methods https://bugzilla.redhat.com/show_bug.cgi?id=514641
+
== Notes to Contributors ==
 +
 
 +
=== 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:
 +
* To install the package '''claws-mail''', read [[User Guide - Managing Software|the chapter on managing software]].  You can install '''claws-mail''' by either [[User Guide - Managing Software#Installing Software|using the PackageKit application]] or on the command line by [[User Guide - Managing Software#Installing Software 2|using Yum]].  More information about Claws Mail is available at: http://claws-mail.org/.
 +
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.
 +
--[[User:Danielsmw|Danielsmw]] 15:08, 25 February 2009 (UTC)
 +
 
 +
=== 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:
 +
{{Admon/important|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.
 +
--[[User:Danielsmw|Danielsmw]] 15:08, 25 February 2009 (UTC)
 +
 
 +
== admin tasks TODO ==
 +
*Find out where git commits are going -  ie not to someplace I am already subscribed to
 +
*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.

Revision as of 19:36, 22 September 2010

Contents

General LifeCycle of the User Guide

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.

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.

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.

How to do the reviews

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

  • Use most current release candidate
  • 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).
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.
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.

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.


F14 Status table

  • When you claim a chapter to review, place your name in the column.
  • When the review is complete, update the status.


  • Integrate Matthew's updates for
    • Finding Software -
  • Update screen shots (desktops) as needed
  • Update Revision History, Book Info, and ent for version 14
  • verify all authors are added to Contributors_and_production_methods.xml and Revision_History.xml

Notes to Contributors

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)

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)

admin tasks TODO

  • Find out where git commits are going - ie not to someplace I am already subscribed to
  • 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.