(hit the wrong reply button)
-------- Mensagem encaminhada -------- Assunto: Re: Documenting how to develop with & for LibreOffice - a fresh approach? Data: Mon, 25 Jul 2016 15:59:35 -0300 De: Olivier Hallot <olivier.hal...@libreoffice.org> Para: libreoff...@lists.freedesktop.org Hello Bjoern, Thorsten, All Em 23/07/2016 22:48, Bjoern Michaelsen escreveu: > Hi, > > On Sun, Jul 24, 2016 at 01:50:20AM +0200, Thorsten Behrens wrote: >> It seems interesting in a number of aspects; perhaps here's a way to >> raise the profile & quality of our own programmability documentation >> (by going there, or by cherry-picking good ideas)? > > Hmm, I dont see much difference here between "stack exchange" and "stack > exchange documentation". What exactly makes the difference there? Because I > dont seem much (yet?). I saw it as a way to create a TOC that links to entries that contains carefully cratfted "questions" with precise and rich answers, using the S.O. engine. > > Also what is the difference between SE and ask.libreoffice.org from a > feature perspective? For example, askubuntu.com is running on the SE stack, > not > on askbot -- but TBH I dont see much difference featurewise. I assume its > mostly done for visibility. I'm no expert but I see 2 softwares for the same purpose: create a knowledge base feeded by the community of users, with the expectation that answers to any question in the universe will show up filtering massive Q's and A's. Reality shows not so easy. Stack Overflow and Askbot are not a panacea but the bottom line is very positive anyway. I moderate brazilian askbot and it works. But the quality of either questions and answers are rarely acceptable as a reference on the topic. People never search for topic before asking, thus lots of repetition. People also don't use the voting system or even bother do downvote bad answers (can spark emotions if you do). Maybe this is community-related, but it is a fact. Therefore, as I said above, carefull questions and rich & precise answers equals workload anyway. > > In general, I _love_ the idea to move our documentation focus to dynamic > content > on a platform that is easy to contribute to -- be that SE or askbot. That is > _way_ more relevant and a much better fit to our development model than aiming > for dead tree editions of documentation. and wiki too. But like software development, we accept "patches" on our doc only after peer review. Believe me, there is no better rich editor than Writer and with a good DMS, unbeatable. > > The thing that askbot/SE misses vs. classical documentation is that a > structure > beyond one topic and a way to focus and highlight a set of well-maintained > content. A possible approach to this would be to have an index of highly > relevant and well maintained content (this index could be in e.g. in the TDF > wiki linking to various askbot/SE topics). The problem with askbot/SE/wikis is > not the so much providing good content, it is making this content discoverable > (dead tree documentation is even worse at this, though) and not sink in > outdated and irrelevant content. right, but mixing different tools is a maintenance nightmare. Nevertheless, discoverability of the documentation/information is one of my concerns at them moment. > > So -- a draft proposal: Lets have an index of highly relevance topics > somewhere > (e.g. on the Wiki) and link the content by topic/chapter to well maintained > and > edited pages on askbot/SE whatever. It can even be the Local Help, one F1 strike far. But see below. > > @Olivier: Unless there are better proposal on how to work on this, could take > up this rough idea and with the help of others grind a diamond out of it? > Thorsten is right, we should any inspiration we can from SE. But even more > importantly we should focus on getting dynamic content up in shape, it is > _way_ > more important than printable, static dead documentation. Today we have this documentation format scenario: - Localhelp, that contains a reference and a user guide, localized with pootle, downloadable. Online version at help.libreoffice.org, XML files. - LO Guides Books, produced in odt format, localizable with CAT by the communities. Rich content, ease of edition. - Askbot: on-line, user driven knowledge base, not localized, per language. - TDF wiki: Some communities produce Q&A's and localized doc here. - external, amateur blogs on LO topics, hints, tips&tricks (I'd like to PLANETIZE this) - other, found by googling around. My take is that there is no one-size-fits-all, very hard not to duplicate workload. Books/chapters/sections are important for the training/migration industry, and is the fastest way to port the documentation to other languages. With a DMS (Document Management System) holding odf files and good documentation project it can be the source for other formats. Finally, on a totally different view, and addressing Thorsten concern on software development documentation, opening a specific askbot instance for developers looks very interesting to turn sterile doxygen documentation into something readable for the rookie developer. regards -- Olivier Hallot Comunidade LibreOffice Rio de Janeiro - Brazil - Local time: UTC-03 http://ask.libreoffice.org/pt-br -- Olivier Hallot Comunidade LibreOffice Rio de Janeiro - Brazil - Local time: UTC-03 http://ask.libreoffice.org/pt-br -- To unsubscribe e-mail to: documentation+unsubscr...@global.libreoffice.org Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/ Posting guidelines + more: http://wiki.documentfoundation.org/Netiquette List archive: http://listarchives.libreoffice.org/global/documentation/ All messages sent to this list will be publicly archived and cannot be deleted