User:Crantila/What up Docs

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 [1]
• Pete Travis notes Publican-based documentation has a high "barrier to entry" [2]
  • Christopher Antila agrees DocBook, Git, and Publican require effort to learn [3]
  • Christopher Antila suggests the pandoc tool may let us let authors use other markup languages [4]
  • Eric Christensen suggests proper training is the solution [5]
  • Chris Murphy suggests Simplified DocBook as a start [6]
  • Now with improved support from Pete Travis [7]
• Pete Travis proposes an additional Docs website with easier syntax and "tutorial-format" and shorter documentation [8][9]
  • Zachary Oglesby suggests the wiki is the proper place for this type of documentation [10]
    • Chris Roberts says he's improving wiki-searching to help with this [11]

• 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]
  • Pete Travis and Jérôme Fenal agree, with the proviso there is a mentor willing to help with the conversion to DocBook [17][18]
• Eric Christensen says LibreOffice can export to DocBook XML, but not particularly effectively [19]

• Leslie Satenstein asks if Transifex allows peer review [20]
  • Eric Christensen says it does [21]
• 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]
  • Christopher Antila agrees Transifex is a productive solution for translation [24]

• Kevin Glazenburg agrees the current workflow is difficult to learn, and suggests simple tasks for starting out [25]

• Eric Christensen says he thinks DocBook XML is easy, and other solutions limit him [26]
• Eric Christensen wants to avoid switching source formats because we'll have "legacy docs" for a long time [27]
• Eric Christensen says we can't lose the multi-format outputs and website-creation Publican gives us [28]
  • Christopher Antila agrees Publican has many strengths and is important [29]
• Eric Christensen says educating people why we use DocBook is a good idea [30]
• Eric Christensen says we could improve the structure of Guides to help people find things [31]

• Jérôme Fenal suggests asking how JBoss.org handles their documentation [32]

• 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]
  • Zachary Oglesby says the wiki and docs.fp.o are difficult to search, and we should solve that [34]
  • Chris Roberts says he's improving wiki-searching to help with this [35]
  • Christopher Antila agrees searching the website is quite difficult [36]
  • Eric Christensen suggests reducing topical overlap between Guides will help with this [37]
    • Jaromir Hradilek says people are trying to reduce the overlap between the System Administrator's Guide and the Installation Guide [38]

• Eric Christensen reinforces that we shouldn't give up our existing tools, and proposes instructional videos [39]
• Chris Murphy supports instructional videos [40]

• Zachary Oglesby says Fedora Docs works very differently compared to other distributions' docs teams [41]
  • Christopher Antila suggests collaborating across distributions [42]

• 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]

• Christopher Antila suggests we try out different (text-editing) tools to use before Publican [46]
  • Eric Christensen believes most Docs contributors use vi(m) or emacs [47]
  • Jaromir Hradilek suggests Gedit, Emacs, or Vim, all of which support DocBook with snippets [48]
  • Shaun McCance says Yelp, the GNOME help viewer, renders DocBook "on the fly" [49]
    • Jaromir Hradilek says he uses Yelp to help [50]

• Christopher Antila suggests using the general climate of workflow-change in Fedora to improve Docs too [51]

• 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]
  • Christopher Antila notes we could use Bugzilla for this [55]

• 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]