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 http://johnmacfarlane.net/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]
• Pete Travis proposes an additional Docs website with easier syntax and "tutorial-format" and shorter documentation [7][8]
  • Zachary Oglesby suggests the wiki is the proper place for this type of documentation [9]
    • Chris Roberts says he's improving wiki-searching to help with this [10]

• Leslie Satenstein proposes LibreOffice (with revision management) replace DocBook [11]
  • Joe Brockmeier notes "many-at-once" is a problem with LibreOffice revision management [12]
  • Pete Travis says distributed version control is more efficient than the paper-workflow-inspired LibreOffice suggestion [13]
  • Christopher Antila agrees distributed version control is important [14]
• Chris Murphy suggests we accept many formats for initial submission of documentation, then convert it [15]
  • Pete Travis and Jérôme Fenal agree, with the proviso there is a mentor willing to help with the conversion to DocBook [16][17]
• Eric Christensen says LibreOffice can export to DocBook XML, but not particularly effectively [18]

• Leslie Satenstein asks if Transifex allows peer review [19]
  • Eric Christensen says it does [20]
• Leslie Satenstein suggests enable offline work on mobile devices [21]
• 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 [22]
  • Christopher Antila agrees Transifex is a productive solution for translation [23]

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

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

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

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

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

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

• Christopher Antila says he feels discouraged from updating Guides between Fedora releases, and suggests de-coupling many Guides' publication from Fedora releases [41]
  • Eric Christensen doesn't know why Christopher feels that way, since he (Eric) re-publishes the Amateur Radio Guide between Fedora releases [42]

• Christopher Antila suggests we try out different (text-editing) tools to use before Publican [43]
  • Eric Christensen believes most Docs contributors use vi(m) or emacs [44]

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

• Chris Murphy wonders if fear of criticism is a factor leading to lower-quality documentation and less engagement [46]

• Chris Murphy seems to have (correctly) guessed the procedure for filing bugs against documentation [47]

• Leslie Satenstein suggests a "social" job-tracker for Docs tasks [48]
  • Christopher Antila notes we could use Bugzilla for this [49]

• Leslie Satensetin says we should ask the community how they'd like to be engaged [50]

• Leslie Satenstein suggests targeting retirees as potential contributors [51]

• Leslie Satenstein questions the anglo-centric development process [52]
  • 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 [53]