User:Crantila/What up Docs

From FedoraProject

< User:Crantila
Revision as of 04:50, 24 November 2013 by Crantila (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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]