Date: Wed, 29 May 2013 22:05:55 +0200 From: Benedict Reuschling <bcr@FreeBSD.org> To: hackers@FreeBSD.org Subject: Summary of the Documentation Working Group at the BSDCan 2013 DevSummit Message-ID: <51A65FA3.4040602@FreeBSD.org>
next in thread | raw e-mail | index | archive | help
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Hello all, this a summary of the doc working group at the BSDCan 2013 DevSummit for those who could not attend but wanted to be kept in the loop about what is going on. Excuse my non-brevity, we had a lot to talk about. Some personal notes are in there, but the rest is written in a neutral style. No presentations were given in the session itself, we worked with the wiki page and recorded everything in an openetherpad document, upon which this summary is based. Overview: The documentation working group had formulated a number of topics on the wiki [1] before the working group began and we managed to cover all of those. I, as one of the two chairpersons for this group (the other being Dru Lavigne like in previous years), was pleasantly surprised that we had more attendees and even some that had never been to one of our doc working groups before. On a personal note, it was also the first time that all of my present and past doc mentees were in the same room together, which made me very happy that this was possible. The previous day at the vendor summit, a number of issues came up that fall into the documentation area like the website. George Neville-Neil, who lead that session, took these items for himself. Having recently been awarded a doc commit bit himself, he was also in our documentation session and provided his unique insights not only as a long time src committer, but also as a book author, which in my opinion helped a lot in some of the discussions we had. Topic #1: Handbook print edition We talked about this almost half the time of the first session before the break. Dru Lavigne gave an update on what work had been done up to this point by her in the ISBN repo branch [2]. The first pass of the handbook is mostly completed, which resulted in a number of writing style and whitespace fixes in preparation for bigger content changes to come. In addition to the already huge todo list [3], she prepared a second one with notes [4] (will be merged into [3] at some point) about each individual section. For the second round of content changes that are required to bring the handbook into FreeBSD 9.X-only world, we need to tap specific developers on the shoulders to get their information for missing content. The observation was that asking on a mailing list does not bring enough people in to help. A list of people was created (table 2 in [3]) that have done work in specific areas where we need their insights about whether content is still accurate or needs to be rewritten to reflect the current state of the system. Doc developers that are interested in these sections will contact these developers and ask for their help. The working group especially reiterated an important point and I would like to repeat it here to make it clear for everyone who is reluctant (to say the least) to write documentation: It is content we need, not markup. If you as a developer provide us with a few paragraphs of a textual description, we will gladly take it and take care of the markup/formatting/editing work that is required ourselves. We might get back to you to clarify content things, but everything else is something that doc developers would be happy to take off your shoulders if it is too much of a hassle for you developers! Another topic that came up with making drastic content changes and chapter/section rearrangements on the handbook in the ISBN branch is that some doc developers are worried that they might receive pushback from others worrying about the state of the handbook and asking for reverts of changes. This has happened in the past with the deactivation of the PGP keys section in the branch (not the live handbook on www.freebsd.org), which would reduce the current PDF from 1491 to 954 pages, which is still a huge number. The argument was that having the keys (or at least a few important ones like the secteam keys) are important for verification, but the room consensus was that these are unnecessary in a printed book. While this specific issue has already been resolved, it is an example of what might occur in the future once the doc team starts to make big changes which others won't like. The consensus was (and gnn@ confirmed this to me after the session was over by independently talking to core members about it) as follows: Editorial choices are the choice of the doc team, However, edits which inadvertently break technical meaning need to be reverted/fixed. I think this is in everyones interest. We don't want people to be completely silent with feedback and discussions about these changes, while at the same time stopping progress that needs to happen in a handbook that has a huge need for fresh and the removal of obsolete content. Print on demand was briefly touched on by David Chisnall and Michael Lucas who could provide contacts with publishers specialising in low-volume print runs for people willing to write FreeBSD-related books. Topic #2: www.freebsd.org website redesign This was previously discussed at the Cambridge DevSummit last year and some of the feedback from the vendor summit the day before (see above) was also brought in. Many suggestions were made in improving the search feature, which does not work very well at the moment. Things like the need for a content management system (separating content from layout), missing links to the wiki and the FreeBSD forums, twitter/social media integration ideas while still making the site easy to manage were debated. Generally, the website is another big project for the documentation team and we agreed that a small team of interested individuals should form and send a mail to ask for participation and to brainstorm ideas. Topic #3: documentation infrastructural changes This was only briefly touched on as Glen Barber reported that he was in contact with Gabor Kovesdan for importing a newer DocBook version into the main tree, which Gabor has been working in a branch for a while now. EPUB support that this change will bring (along with other important improvements like conditional text to mark release specific sections) is something that I personally have been looking forward to. The reason is that once the handbook is ready for publishing via the FreeBSD Mall, we will also provide ebook versions for people to pay for with receipts going back to the FreeBSD foundation as donations. This will hopefully provide another incentive for people to work on documentation when they see that this supports the FreeBSD project in a different way than it has now. Topic #4: Recruiting new doc committers/contributors Recruiting new doc committers is another topic we talked about, since our ranks are still low compared to the ports or source people. Clearly, part of our current problems is that we lack the people to do many of the things we want to accomplish in our documentation set. Ideas revolved around talking to people who write howtos on the FreeBSD forums, create a separate user wiki for content submissions, an option for each handbook page to add notes (like the PostgreSQL project has) and finding a suitable DocBook Editor so people don't have to worry too much about the markup and can just focus on providing content. Topic #5: Helping our translation projects keeping up with changes Helping the translation teams was a topic that I put in being a member of the FreeBSD German Documentation Project and observing similar things happening in the other language teams: we can't keep up. In most of our translation projects, only two people (the former mentee and his/her mentor) try to catch up with the work that few very active (which is a good thing, mind you!) committers are doing in the english reference tree. I'm investigating textproc/pootle at the moment as an alternative way of getting additional translations by reusing already translated strings. PC-BSD apparently has some success with it and I was thinking about sharing their database since both systems use the same basic terminology. I had the chance during the conference to talk to Kris Moore about this possibility and he said that Pootle needed a lot of extra scripts to be written in order to automate things and to be as helpful as it it for them now. Sharing just the database might be an option, but there are many PC-BSD graphical menu strings in there that simply don't exist in FreeBSD so there won't be much reuse of already translated strings. However, I think this is still better than starting from scratch with a fresh Pootle installation. I'm willing to do more experimenting in that area to come up with a solution. Topic #6: Separate doc hackathon We talked about organizing a separate doc hackathon to get things up to speed, especially in the print edition of the handbook. This would be more focused on doing actual work rather than talking about what needs to be done, with the possibility to talk to people in the room when the need arises. David Chisnall offered room space and logistics for such an event at the Cambridge DevSummit, which has recently been announced. Topic #7 and 8: Blanket doc commit rights A brief topic was giving members of some non-doc teams blanket commit rights (after a mentoring period) to make commits on documents that they maintain mostly, but need to go through a doc person at the moment to do the actual commit. A prominent example is the porters handbook, which is actively maintained by the ports team sending patches in PRs. The goal with such a blanket commit rule is to reduce the workload on the doc committers while allowing these teams to maintain their documents faster. We will work with teams that are open to this idea to have at least one member of their team get a commit bit so that they can channel changes through that person. if a team feels that this is of no added value to them or prefer to go through the doc team first, that is also fine with us. Topic #9: Quality assurance Quality assurance in our documentation set was only briefly touched on as we were already running late in the session. We talked about the possibilities of regular textproc/igor runs that display their findings on a webpage or mailing the results to the doc team. This would either result in igor being improved (due to false positives) or people starting to fix bugs that were reported. Regular link checker runs also should be done as finding broken links is something that a machine is better at than humans are. All in all, it was a very productive session and we continued talking after the session ended, either over dinner or at the Hacking Lounge. I also want to highlight that we had a few people in the doc lounge (running parallel to the Hacking Lounge) that were interested in helping out with documentation work. Doc committers were there to help them get started and a few PRs were filed into GNATS and later resolved as a direct result of these sessions. Clearly, showing someone in person what needs to be done is more effective and yields results faster than doing it via any other means. My thanks go to all who participated and provided insights, feedback, ideas for improvement, support and their experience during the working group session. A big THANK YOU goes to John Baldwin for organizing the DevSummit so well again and all the sponsors that made it possible. If you have questions on any of these topics, feel free to drop me a line. Regards Benedict Reuschling FreeBSD Documentation Committer The FreeBSD Documentation Project FreeBSD German Documentation Project - https://doc.bsdgroup.de [1] https://wiki.freebsd.org/201305DevSummit/Documentation [2] http://svnweb.freebsd.org/doc/projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/ [3] https://wiki.freebsd.org/PublishedFormats [4] http://openetherpad.org/R6vMaCQ1GI -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.8 (Darwin) Comment: GPGTools - http://gpgtools.org Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iEYEARECAAYFAlGmX6MACgkQTSZQLkqBk0iihwCgtP/FO44TPRkP94RN0w+gJO57 6owAn2dc1ZEBOIPUnLGz12rvzgzjzZWk =gu9w -----END PGP SIGNATURE-----
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?51A65FA3.4040602>