From Fedora Project Wiki
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]
- Leslie Satenstein proposes LibreOffice (with revision management) replace DocBook [11]
- Chris Murphy suggests we accept many formats for initial submission of documentation, then convert it [15]
- 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]