User:Crantila/What up Docs

From FedoraProject

< User:Crantila(Difference between revisions)
Jump to: navigation, search
(initial creation!)
 
(added a bunch more stuff)
Line 1: Line 1:
 
This page is about collecting people's thoughts about what's up with Docs in November 2013.
 
This page is about collecting people's thoughts about what's up with Docs in November 2013.
  
* Pete Travis says we need to make room for not-DocBook forms of contribution [https://lists.fedoraproject.org/pipermail/docs/2013-November/015349.html]
+
* [[User:Immanetize|Pete Travis]] says we need to make room for not-DocBook forms of contribution [https://lists.fedoraproject.org/pipermail/docs/2013-November/015349.html]
* Pete Travis notes Publican-based documentation has a high "barrier to entry" [https://lists.fedoraproject.org/pipermail/docs/2013-November/015317.html]
+
* [[User:Immanetize|Pete Travis]] notes Publican-based documentation has a high "barrier to entry" [https://lists.fedoraproject.org/pipermail/docs/2013-November/015317.html]
** Christopher Antila agrees DocBook, Git, and Publican require effort to learn [https://lists.fedoraproject.org/pipermail/docs/2013-November/015332.html]
+
** [[User:Crantila|Christopher Antila]] agrees DocBook, Git, and Publican require effort to learn [https://lists.fedoraproject.org/pipermail/docs/2013-November/015332.html]
** Christopher Antila suggests the [pandoc http://johnmacfarlane.net/pandoc] tool may let us let authors use other markup languages [https://lists.fedoraproject.org/pipermail/docs/2013-November/015332.html]
+
** [[User:Crantila|Christopher Antila]] suggests the [http://johnmacfarlane.net/pandoc pandoc] tool may let us let authors use other markup languages [https://lists.fedoraproject.org/pipermail/docs/2013-November/015332.html]
** Eric Christensen suggests proper training is the solution [https://lists.fedoraproject.org/pipermail/docs/2013-November/015334.html]
+
** [[User:Sparks|Eric Christensen]] suggests proper training is the solution [https://lists.fedoraproject.org/pipermail/docs/2013-November/015334.html]
 
** Chris Murphy suggests Simplified DocBook as a start [https://lists.fedoraproject.org/pipermail/docs/2013-November/015355.html]
 
** Chris Murphy suggests Simplified DocBook as a start [https://lists.fedoraproject.org/pipermail/docs/2013-November/015355.html]
* Pete Travis proposes an additional Docs website with easier syntax and "tutorial-format" and shorter documentation [https://lists.fedoraproject.org/pipermail/docs/2013-November/015317.html][https://lists.fedoraproject.org/pipermail/docs/2013-November/015325.html]
+
** Now with improved support from [[User:Immanetize|Pete Travis]] [https://lists.fedoraproject.org/pipermail/docs/2013-November/015344.html]
** Zachary Oglesby suggests the wiki is the proper place for this type of documentation [https://lists.fedoraproject.org/pipermail/docs/2013-November/015330.html]
+
* [[User:Immanetize|Pete Travis]] proposes an additional Docs website with easier syntax and "tutorial-format" and shorter documentation [https://lists.fedoraproject.org/pipermail/docs/2013-November/015317.html][https://lists.fedoraproject.org/pipermail/docs/2013-November/015325.html]
*** Chris Roberts says he's improving wiki-searching to help with this [https://lists.fedoraproject.org/pipermail/docs/2013-November/015331.html]
+
** [[User:Zoglesby|Zachary Oglesby]] suggests the wiki is the proper place for this type of documentation [https://lists.fedoraproject.org/pipermail/docs/2013-November/015330.html]
 +
*** [[User:Chrisroberts|Chris Roberts]] says he's improving wiki-searching to help with this [https://lists.fedoraproject.org/pipermail/docs/2013-November/015331.html]
  
 
* Leslie Satenstein proposes LibreOffice (with revision management) replace DocBook [https://lists.fedoraproject.org/pipermail/docs/2013-November/015318.html]
 
* Leslie Satenstein proposes LibreOffice (with revision management) replace DocBook [https://lists.fedoraproject.org/pipermail/docs/2013-November/015318.html]
** Joe Brockmeier notes "many-at-once" is a problem with LibreOffice revision management [https://lists.fedoraproject.org/pipermail/docs/2013-November/015319.html]
+
** [[User:Jzb|Joe Brockmeier]] notes "many-at-once" is a problem with LibreOffice revision management [https://lists.fedoraproject.org/pipermail/docs/2013-November/015319.html]
** Pete Travis says distributed version control is more efficient than the paper-workflow-inspired LibreOffice suggestion [https://lists.fedoraproject.org/pipermail/docs/2013-November/015320.html]
+
** [[User:Immanetize|Pete Travis]] says distributed version control is more efficient than the paper-workflow-inspired LibreOffice suggestion [https://lists.fedoraproject.org/pipermail/docs/2013-November/015320.html]
** Christopher Antila agrees distributed version control is important [https://lists.fedoraproject.org/pipermail/docs/2013-November/015332.html]
+
** [[User:Crantila|Christopher Antila]] agrees distributed version control is important [https://lists.fedoraproject.org/pipermail/docs/2013-November/015332.html]
 
* Chris Murphy suggests we accept many formats for initial submission of documentation, then convert it [https://lists.fedoraproject.org/pipermail/docs/2013-November/015340.html]
 
* Chris Murphy suggests we accept many formats for initial submission of documentation, then convert it [https://lists.fedoraproject.org/pipermail/docs/2013-November/015340.html]
** Pete Travis and Jérôme Fenal agree, with the proviso there is a mentor willing to help with the conversion to DocBook [https://lists.fedoraproject.org/pipermail/docs/2013-November/015347.html][https://lists.fedoraproject.org/pipermail/docs/2013-November/015348.html]
+
** [[User:Immanetize|Pete Travis]] and [[User:jfenal|Jérôme Fenal]] agree, with the proviso there is a mentor willing to help with the conversion to DocBook [https://lists.fedoraproject.org/pipermail/docs/2013-November/015347.html][https://lists.fedoraproject.org/pipermail/docs/2013-November/015348.html]
* Eric Christensen says LibreOffice can export to DocBook XML, but not particularly effectively [https://lists.fedoraproject.org/pipermail/docs/2013-November/015345.html]
+
* [[User:Sparks|Eric Christensen]] says LibreOffice can export to DocBook XML, but not particularly effectively [https://lists.fedoraproject.org/pipermail/docs/2013-November/015345.html]
  
 
* Leslie Satenstein asks if Transifex allows peer review [https://lists.fedoraproject.org/pipermail/docs/2013-November/015322.html]
 
* Leslie Satenstein asks if Transifex allows peer review [https://lists.fedoraproject.org/pipermail/docs/2013-November/015322.html]
** Eric Christensen says it does [https://lists.fedoraproject.org/pipermail/docs/2013-November/015329.html]
+
** [[User:Sparks|Eric Christensen]] says it does [https://lists.fedoraproject.org/pipermail/docs/2013-November/015329.html]
 
* Leslie Satenstein suggests enable offline work on mobile devices [https://lists.fedoraproject.org/pipermail/docs/2013-November/015322.html]
 
* Leslie Satenstein suggests enable offline work on mobile devices [https://lists.fedoraproject.org/pipermail/docs/2013-November/015322.html]
* John J. McDonough notes that translation teams in different languages work differently; implies it's Docs' responsibility to get things into Transifex and stop worrying [https://lists.fedoraproject.org/pipermail/docs/2013-November/015327.html]
+
* [[User:jjmcd|John J. McDonough]] notes that translation teams in different languages work differently; implies it's Docs' responsibility to get things into Transifex and stop worrying [https://lists.fedoraproject.org/pipermail/docs/2013-November/015327.html]
** Christopher Antila agrees Transifex is a productive solution for translation [https://lists.fedoraproject.org/pipermail/docs/2013-November/015332.html]
+
** [[User:Crantila|Christopher Antila]] agrees Transifex is a productive solution for translation [https://lists.fedoraproject.org/pipermail/docs/2013-November/015332.html]
  
 
* Kevin Glazenburg agrees the current workflow is difficult to learn, and suggests simple tasks for starting out [https://lists.fedoraproject.org/pipermail/docs/2013-November/015321.html]
 
* Kevin Glazenburg agrees the current workflow is difficult to learn, and suggests simple tasks for starting out [https://lists.fedoraproject.org/pipermail/docs/2013-November/015321.html]
  
* Eric Christensen says he thinks DocBook XML is easy, and other solutions limit him [https://lists.fedoraproject.org/pipermail/docs/2013-November/015323.html]
+
* [[User:Sparks|Eric Christensen]] says he thinks DocBook XML is easy, and other solutions limit him [https://lists.fedoraproject.org/pipermail/docs/2013-November/015323.html]
* Eric Christensen wants to avoid switching source formats because we'll have "legacy docs" for a long time [https://lists.fedoraproject.org/pipermail/docs/2013-November/015323.html]
+
* [[User:Sparks|Eric Christensen]] wants to avoid switching source formats because we'll have "legacy docs" for a long time [https://lists.fedoraproject.org/pipermail/docs/2013-November/015323.html]
* Eric Christensen says we can't lose the multi-format outputs and website-creation Publican gives us [https://lists.fedoraproject.org/pipermail/docs/2013-November/015323.html]
+
* [[User:Sparks|Eric Christensen]] says we can't lose the multi-format outputs and website-creation Publican gives us [https://lists.fedoraproject.org/pipermail/docs/2013-November/015323.html]
** Christopher Antila agrees Publican has many strengths and is important [https://lists.fedoraproject.org/pipermail/docs/2013-November/015332.html]
+
** [[User:Crantila|Christopher Antila]] agrees Publican has many strengths and is important [https://lists.fedoraproject.org/pipermail/docs/2013-November/015332.html]
* Eric Christensen says educating people why we use DocBook is a good idea [https://lists.fedoraproject.org/pipermail/docs/2013-November/015323.html]
+
* [[User:Sparks|Eric Christensen]] says educating people why we use DocBook is a good idea [https://lists.fedoraproject.org/pipermail/docs/2013-November/015323.html]
* Eric Christensen says we could improve the structure of Guides to help people find things [https://lists.fedoraproject.org/pipermail/docs/2013-November/015323.html]
+
* [[User:Sparks|Eric Christensen]] says we could improve the structure of Guides to help people find things [https://lists.fedoraproject.org/pipermail/docs/2013-November/015323.html]
  
* Jérôme Fenal suggests asking how JBoss.org handles their documentation [https://lists.fedoraproject.org/pipermail/docs/2013-November/015324.html]
+
* [[User:jfenal|Jérôme Fenal]] suggests asking how JBoss.org handles their documentation [https://lists.fedoraproject.org/pipermail/docs/2013-November/015324.html]
  
* Eric Christensen is wary of adding a third source of documentation (over docs.fp.o and the wiki) because it's already difficult to search [https://lists.fedoraproject.org/pipermail/docs/2013-November/015328.html]
+
* [[User:Sparks|Eric Christensen]] is wary of adding a third source of documentation (over docs.fp.o and the wiki) because it's already difficult to search [https://lists.fedoraproject.org/pipermail/docs/2013-November/015328.html]
** Zachary Oglesby says the wiki and docs.fp.o are difficult to search, and we should solve that [https://lists.fedoraproject.org/pipermail/docs/2013-November/015330.html]
+
** [[User:Zoglesby|Zachary Oglesby]] says the wiki and docs.fp.o are difficult to search, and we should solve that [https://lists.fedoraproject.org/pipermail/docs/2013-November/015330.html]
** Chris Roberts says he's improving wiki-searching to help with this [https://lists.fedoraproject.org/pipermail/docs/2013-November/015331.html]
+
** [[User:Chrisroberts|Chris Roberts]] says he's improving wiki-searching to help with this [https://lists.fedoraproject.org/pipermail/docs/2013-November/015331.html]
** Christopher Antila agrees searching the website is quite difficult [https://lists.fedoraproject.org/pipermail/docs/2013-November/015332.html]
+
** [[User:Crantila|Christopher Antila]] agrees searching the website is quite difficult [https://lists.fedoraproject.org/pipermail/docs/2013-November/015332.html]
** Eric Christensen suggests reducing topical overlap between Guides will help with this [https://lists.fedoraproject.org/pipermail/docs/2013-November/015334.html]
+
** [[User:Sparks|Eric Christensen]] suggests reducing topical overlap between Guides will help with this [https://lists.fedoraproject.org/pipermail/docs/2013-November/015334.html]
 +
*** [[User:Jhradile|Jaromir Hradilek]] says people are trying to reduce the overlap between the '''System Administrator's Guide''' and the '''Installation Guide''' [https://lists.fedoraproject.org/pipermail/docs/2013-November/015343.html]
  
* Eric Christensen reinforces that we shouldn't give up our existing tools, and proposes instructional videos [https://lists.fedoraproject.org/pipermail/docs/2013-November/015328.html]
+
* [[User:Sparks|Eric Christensen]] reinforces that we shouldn't give up our existing tools, and proposes instructional videos [https://lists.fedoraproject.org/pipermail/docs/2013-November/015328.html]
 
* Chris Murphy supports instructional videos [https://lists.fedoraproject.org/pipermail/docs/2013-November/015340.html]
 
* Chris Murphy supports instructional videos [https://lists.fedoraproject.org/pipermail/docs/2013-November/015340.html]
  
* Zachary Oglesby says Fedora Docs works very differently compared to other distributions' docs teams [https://lists.fedoraproject.org/pipermail/docs/2013-November/015330.html]
+
* [[User:Zoglesby|Zachary Oglesby]] says Fedora Docs works very differently compared to other distributions' docs teams [https://lists.fedoraproject.org/pipermail/docs/2013-November/015330.html]
** Christopher Antila suggests collaborating across distributions [https://lists.fedoraproject.org/pipermail/docs/2013-November/015332.html]
+
** [[User:Crantila|Christopher Antila]] suggests collaborating across distributions [https://lists.fedoraproject.org/pipermail/docs/2013-November/015332.html]
  
* Christopher Antila says he feels discouraged from updating Guides between Fedora releases, and suggests de-coupling many Guides' publication from Fedora releases [https://lists.fedoraproject.org/pipermail/docs/2013-November/015332.html]
+
* [[User:Crantila|Christopher Antila]] says he feels discouraged from updating Guides between Fedora releases, and suggests de-coupling many Guides' publication from Fedora releases [https://lists.fedoraproject.org/pipermail/docs/2013-November/015332.html]
** Eric Christensen doesn't know why Christopher feels that way, since he (Eric) re-publishes the Amateur Radio Guide between Fedora releases [https://lists.fedoraproject.org/pipermail/docs/2013-November/015334.html]
+
** [[User:Sparks|Eric Christensen]] doesn't know why Christopher feels that way, since he (Eric) re-publishes the Amateur Radio Guide between Fedora releases [https://lists.fedoraproject.org/pipermail/docs/2013-November/015334.html]
 +
** [[User:Immanetize|Pete Travis]] also suggests a sort of "rolling release" for certain Guides [https://lists.fedoraproject.org/pipermail/docs/2013-November/015344.html]
  
* Christopher Antila suggests we try out different (text-editing) tools to use before Publican [https://lists.fedoraproject.org/pipermail/docs/2013-November/015332.html]
+
* [[User:Crantila|Christopher Antila]] suggests we try out different (text-editing) tools to use before Publican [https://lists.fedoraproject.org/pipermail/docs/2013-November/015332.html]
** Eric Christensen believes most Docs contributors use vi(m) or emacs [https://lists.fedoraproject.org/pipermail/docs/2013-November/015345.html]
+
** [[User:Sparks|Eric Christensen]] believes most Docs contributors use vi(m) or emacs [https://lists.fedoraproject.org/pipermail/docs/2013-November/015345.html]
 +
** [[User:Jhradile|Jaromir Hradilek]] suggests gedit and vim, both of which have support DocBook with snippets [https://lists.fedoraproject.org/pipermail/docs/2013-November/015343.html]
 +
** Shaun McCance says ''Yelp'', the GNOME help viewer, renders DocBook "on the fly" [https://lists.fedoraproject.org/pipermail/docs/2013-November/015336.html]
 +
*** [[User:Jhradile|Jaromir Hradilek]] says he uses ''Yelp'' to help [https://lists.fedoraproject.org/pipermail/docs/2013-November/015341.html]
  
* Christopher Antila suggests using the general climate of workflow-change in Fedora to improve Docs too [https://lists.fedoraproject.org/pipermail/docs/2013-November/015342.html]
+
* [[User:Crantila|Christopher Antila]] suggests using the general climate of workflow-change in Fedora to improve Docs too [https://lists.fedoraproject.org/pipermail/docs/2013-November/015342.html]
  
 
* Chris Murphy wonders if fear of criticism is a factor leading to lower-quality documentation and less engagement [https://lists.fedoraproject.org/pipermail/docs/2013-November/015340.html]
 
* Chris Murphy wonders if fear of criticism is a factor leading to lower-quality documentation and less engagement [https://lists.fedoraproject.org/pipermail/docs/2013-November/015340.html]
Line 61: Line 67:
  
 
* Leslie Satenstein suggests a "social" job-tracker for Docs tasks [https://lists.fedoraproject.org/pipermail/docs/2013-November/015356.html]
 
* Leslie Satenstein suggests a "social" job-tracker for Docs tasks [https://lists.fedoraproject.org/pipermail/docs/2013-November/015356.html]
** Christopher Antila notes we could use Bugzilla for this [https://lists.fedoraproject.org/pipermail/docs/2013-November/015357.html]
+
** [[User:Crantila|Christopher Antila]] notes we could use Bugzilla for this [https://lists.fedoraproject.org/pipermail/docs/2013-November/015357.html]
  
 
* Leslie Satensetin says we should ask the community how they'd like to be engaged [https://lists.fedoraproject.org/pipermail/docs/2013-November/015356.html]
 
* Leslie Satensetin says we should ask the community how they'd like to be engaged [https://lists.fedoraproject.org/pipermail/docs/2013-November/015356.html]
Line 68: Line 74:
  
 
* Leslie Satenstein questions the anglo-centric development process [https://lists.fedoraproject.org/pipermail/docs/2013-November/015356.html]
 
* Leslie Satenstein questions the anglo-centric development process [https://lists.fedoraproject.org/pipermail/docs/2013-November/015356.html]
** Christopher Antila notes one Guide was first contributed in Spanish; it's because our tools are designed for one source language and Red Hat is American; and collaborating across linguistic barriers is potentially risky [https://lists.fedoraproject.org/pipermail/docs/2013-November/015357.html]
+
** [[User:Crantila|Christopher Antila]] notes one Guide was first contributed in Spanish; it's because our tools are designed for one source language and Red Hat is American; and collaborating across linguistic barriers is potentially risky [https://lists.fedoraproject.org/pipermail/docs/2013-November/015357.html]

Revision as of 06:10, 24 November 2013

This page is about collecting people's thoughts about what's up with Docs in November 2013.

  • Leslie Satenstein proposes LibreOffice (with revision management) replace DocBook [12]
    • Joe Brockmeier notes "many-at-once" is a problem with LibreOffice revision management [13]
    • Pete Travis says distributed version control is more efficient than the paper-workflow-inspired LibreOffice suggestion [14]
    • Christopher Antila agrees distributed version control is important [15]
  • Chris Murphy suggests we accept many formats for initial submission of documentation, then convert it [16]
  • Eric Christensen says LibreOffice can export to DocBook XML, but not particularly effectively [19]
  • Leslie Satenstein asks if Transifex allows peer review [20]
  • Leslie Satenstein suggests enable offline work on mobile devices [22]
  • John J. McDonough notes that translation teams in different languages work differently; implies it's Docs' responsibility to get things into Transifex and stop worrying [23]
  • Kevin Glazenburg agrees the current workflow is difficult to learn, and suggests simple tasks for starting out [25]
  • Eric Christensen is wary of adding a third source of documentation (over docs.fp.o and the wiki) because it's already difficult to search [33]
  • Eric Christensen reinforces that we shouldn't give up our existing tools, and proposes instructional videos [39]
  • Chris Murphy supports instructional videos [40]
  • Christopher Antila says he feels discouraged from updating Guides between Fedora releases, and suggests de-coupling many Guides' publication from Fedora releases [43]
    • Eric Christensen doesn't know why Christopher feels that way, since he (Eric) re-publishes the Amateur Radio Guide between Fedora releases [44]
    • Pete Travis also suggests a sort of "rolling release" for certain Guides [45]
  • Chris Murphy wonders if fear of criticism is a factor leading to lower-quality documentation and less engagement [52]
  • Chris Murphy seems to have (correctly) guessed the procedure for filing bugs against documentation [53]
  • Leslie Satenstein suggests a "social" job-tracker for Docs tasks [54]
  • Leslie Satensetin says we should ask the community how they'd like to be engaged [56]
  • Leslie Satenstein suggests targeting retirees as potential contributors [57]
  • Leslie Satenstein questions the anglo-centric development process [58]
    • Christopher Antila notes one Guide was first contributed in Spanish; it's because our tools are designed for one source language and Red Hat is American; and collaborating across linguistic barriers is potentially risky [59]