Showing posts with label Documentation. Show all posts
Showing posts with label Documentation. Show all posts

Friday, August 17, 2018

Akademy: closing time

Akademy is always a whirlwind which is my excuse for not blogging! Today we wrapped up the program which leaves us in a nearly-empty venue and a bit of time after lunch to catch up.

I did manage to gather photos together in Google Photos: https://photos.app.goo.gl/qHPwehW8C1zPGuav7

Thanks again to the KDE e.V. for sponsoring my hostel and the Ubuntu Community Fund for part of my travel expenses. This allowed me to attend. Meeting Popey from the Ubuntu community and the Limux team was great, although we didn't do as much Kubuntu work as in past years. However, attending the Distro BoF was a great experience; very friendly and collaborative.

As always, the talks were interesting, the "hall track" fascinating, BoFs engaging. The high point for me personally was being given an Akademy Award on Sunday after a blessedly-short e.V. meeting. I almost fainted from surprise! It feels wonderful to be not just appreciated but honored for my work for the KDE community. 

Thank you again!

I will update here with a photo when I can.

Yesterday and today were taken up with trainings, which while exhausting are extremely valuable. Along with the documentation work ahead, I look forward to integrating both the Non-Violent Communication and Tech Documentation trainings into my work.

In addition, I will be happy to see our documentation team re-group and gain strength over the next year as we work with the contractor on identifying pain points and fixing them.

I got lost yesterday, which one should always do in a strange city. Here is one of the beautiful windows I saw before finding the tram and a different way home:

Tomorrow we meet at 3:45 am to share an Uber to the airport and the beginning of the journey home. To KDE friends new and old: we'll meet next year at Akademy I hope, or at least in IRC.

Local friends and family, I'll see you soon!

Sunday, November 27, 2016

KDE Developer Guide needs a new home and some fresh content

As I just posted in the Mission Forum, our KDE Developer Guide needs a new home. Currently it is "not found" where it is supposed to be.

UPDATE: Nicolas found the PDF on archive.org, which does have the photos too. Not as good as the xml, but better than nothing.

We had great luck using markdown files in git for the chapters of the Frameworks Cookbook, so the Devel Guide should be stored and developed in a like manner. I've been reading about Sphinx lately as a way to write documentation, which is another possibility. Kubuntu uses Sphinx for docs.

In any case, I do not have the time or skills to get, restructure and re-place this handy guide for our GSoC students and other new KDE contributors.

This is perhaps suitable for a Google Code-in task, but I would need a mentor who knows markdown or Sphinx to oversee. Contact me if interested! #kde-books or #kde-soc

Sunday, January 11, 2015

Students, Google Summer of Code is coming, but not quite yet....

We've been seeing more and more questions about GSoC and how to get involved.

GSoC 2015 will be happening, but it is not yet time for orgs to even apply, much less be accepted. So we have no ideas page as yet for GSoC 2015.

That said, the best way to have your GSoC proposal accepted is to join
a team NOW and work with them on triaging and fixing bugs, and working
on old and new projects. As you work with your team members and the
codebase, you will be learn how to create a proposal which fits the needs
of the project, and also find willing and able mentors willing to guide you. Remember, mentoring is hard work. Probable mentors want to choose students they can trust to complete their proposal successfully.

The time to prepare for GSoC is now -- but it is not the time for
creating proposals yet. The important part of GSoC is embedding
yourself into your chosen project.Your energy can transform a project
from one lacking a spark into one brimming with enthusiasm. Go for it!

How to join a team:
  • Find the best list(s) and subscribe, and scan the archives.
  • Join the relevant IRC channels and hang out there All The Time.
  • Search the forum for areas/posts where you can help out.
  • Start searching https://bugs.kde.org for bugs which you can test, and fix.
  • Learn how to propose your code changes to Reviewboard.
Other ways to prepare yourself:
  • Read the KDE Developers manual and prepare your development environment.
  • Read the GSoC Student Manual.
  • As you work your way through the documentation, please fix errors you find, or update it. Remember, documentation is part of the code we provide to both other developers and users.

Tuesday, September 9, 2014

Fixing mistakes and growing stronger

In Creativity, Inc., Catmull explores an example of where their structure had created some problems, and how they identified and fixed that, improving their over-all culture. I know this is a wall of text, but Catmull asks excellent questions. I felt it was worthwhile to copy for you. He says,
Improvements didn't happen overnight. But by the time we finished A Bug's Life, the production managers were no longer seen as impediments to creative process, but as peers--as first-class citizens. We had become better. 
This was success in itself, but it came with an added and unexpected benefit: The act of thinking about the problem and responding to it was invigorating and rewarding. We realized that our purpose was not merely to build a studio that made hit films but to foster a creative culture that would continually ask questions. Questions like: If we had done some things right to achieve success how could we ensure that we understood what those things were? Could we replicate them on our next projects? Perhaps as important, was replication of success even the right thing to do? How many serious, potentially disastrous problems were lurking just out of sight and threatening to undo us? What, if anything, could we do to bring the to light? How much of our success was luck? What would happen to our egos if we continued to succeed? Would they grow so large they could hurt us, and if so, what could we do to address that overconfidence? What dynamics would arise now that we were bringing new people into a successful enterprise as opposed to a struggling startup?

What had drawn me to science, all those years ago, was the search for understanding. Human interaction is far more complex than relativity or string theory, of course, but that only made it more interesting and important; it constantly challenged my presumptions.... Figuring out how to build a sustainable creative culture--one that didn't just pay lip service to the importance of things like honesty, excellence, communication, originality, and self-assessment but really *committed* to them, no matter how uncomfortable that became--wasn't a singular assignment....

As I saw it, our mandate was to foster a culture that would seek to keep our sightlines clear, even as we accepted that we were often trying to engage with and fix what we could not see. My hope was to make this culture so vigorous that it would survive when Pixar's founding members were long gone. [p. 64-5]
Again, I see an almost perfect match between their task and ours, where ours=KDE e.V.. In the Community Working Group (CWG) in particular, I see my task as essentially gardening. This includes improving the soil, weeding, but never removing valuable little shoots which can grow into exciting new directions for the community. Of course I can't carry the metaphor too far, since others do the planting. But we can keep the conditions for growth optimal with our work.

In the documentation workshop yesterday, we explored the current state of the KDE documentation, how we can improve access, and grow the documentation team again. We also found some large choke points, which includes KDE.org. We really need a web team! KDE.org is valuable real estate on the web, which has been neglected for too long. More about that later.....

For now, looking forward to another day of hard work and fun in Brno!


Thursday, October 17, 2013

Celebrating Kubuntu 13.10 release

This was such a nice release. Working with the team as part of the Council has all been delightful, and working with the rest of the documentation team was great, as well. We were very ambitious, and didn't finish all of what we started, but we're very proud of the documentation we're publishing with this release. We plan to finish and polish for the LTS 14.04. I loved being able to test a bit this round, as well.

Besides documentation, Kubuntu has lots of improvements this outing, and we now have paid support available, along with a shirt shop! See http://www.kubuntu.org/news/kubuntu-13.10 for more information. I just ordered my polo shirt, and it took less than 5 minutes. Can't wait for mail from Finland!

I seed all the *buntu torrents each release. This time out, the torrents.ubuntu.com is maxed out! I hope to begin seeding more torrents tomorrow, when the servers are a bit less busy.

Friday, May 17, 2013

Tea and cookies for your new team members

What does every development team want? New contributors!

I'd like to suggest a simple process that can turn visitors to your website, list or IRC channel into a successful part of the development team. When people actually contribute, they quickly feel like a valuable part of the group. New people bring fresh energy, and new ideas.

At your next sprint or meeting, start dreaming. Is your user documentation well-written and up-to-date? Do you need promotion, or video guides? How about art or diagrams for your website? Speaking of your website, when was the last time all the links were tested, and it was checked for spelling and grammar? Create a nice, friendly list of tasks for your newcomers.

Could your codebase use some grooming, for common misspellings, for instance? (EBN is a great source for these). When you run across a bit of code which needs pruning or refactoring, or normalizing signal-slot stuff, the easy thing is to fix it while it's in front of your eyes. Instead, consider which of these small tasks can be filed as a "Junior Job", created for the purpose of getting those knowledgeable people to move from faithful user, to part of the team.

The Bugsquad and Quality Control teams can likely suggest more ideas, too.

KDE Junior Jobs can be easily found: http://kde.org/jj. Teams can create their own shortcut links too, such as Amarok has done, listed in the #amarok IRC channel topic: http://tinyurl.com/amarokjjs. Other tasks can be blogged about, posted on a trello, on the Community wiki; whatever your team likes to use. For more ideas, see http://community.kde.org/Getinvolved.

The Kubuntu team has a list of tasks in Trello, which works well.

So, when you feel like not fixing a little issue, don't feel lazy. Feel responsible! File a bug, make it a JJ, and call attention to those issues when new folks show up and ask, how can I help?


PS: Thanks to the #kde-www team for suggesting this blog. Einar77, neverdingo, mamarok; you are wonderful.

PPS: How LibreOffice does it: https://wiki.documentfoundation.org/Development/Easy_Hacks

Friday, October 21, 2011

New KDE book, Beginning KDE Development!

This week has been amazing! I'm not sure what I expected when I applied for the GSoC Doc Sprint, or when I became part of Karan's team, whichproposed creating a guide for new KDE developers. I know I did NOT expect to have a book in print within the week! However, our wonderful hosts and guides from Google, FlossManuals, and Aspiration http://www.aspirationtech.org/ guided all of us so well, that WE DID IT! Not only the KDE team, but also the people from OpenMRS, OpenStreetMap and Sahana also created and published books! Four books in one week, from 29 people. I still can't believe it. Rohan, Supreet, and Karan (Rohan Garg, Supreet Pal Singh, Karan Pratap Singh) - you are the best!

Publication isn't the end of the process though. In fact, the opposite. Because of the way FlossManuals is set up, the books are in a "rolling release" unless they are deliberately frozen. So interested folks can edit and add over time, or even clone books or chapters to "fork", if needed.

Also, one of the teams was describing how they created a book before, with a co-located coding and documentation sprint. Doesn't that sound like a great idea, KDE teams? As they told it, as the doc team struggled with difficulties, and consulted with the coding team, often the code was made better, cleaner, simpler -- which make the documentation more straightforward as well. It sounds like a great idea; to make the new documentation match exactly the new code, released together at the same time. Sounds like a best practice to me! We did something like this at the Amarok sprint at Randa last summer, and it worked out very well. Since we had Myriam there hunting down bugs too, which was triply effective.

Not every team will want a book, of course. Books aren't always a practical documentation form-factor, although FlossManuals points the way to the future, I think. The books don't have to be printed, but can also be made available as HTML, PDF, or ePub files. Also, the files can be given away or sold, as the project chooses, and the projects set the price on the printed books as well. Since we have make the e.V. the owner of the book, they could even decide to set a higher price for awhile, as a fundraiser, or buy them cheaply in bulk to send to the GSoC students, or make available at KDE booths at FOSS events.

Our book, Beginning KDE Development, was created with the GSoC students in mind, to help them get up and running KDE trunk, if necessary, as quickly as possible. Along with the technical helps, we've also discussed the KDE community, where to get help, and how to communicate -- all in one short book. I hope you will visit http://booki.flossmanuals.net/kde-guide/, create an account, and help us make it better! We have to have it in excellent shape in time for the next group of GSoC students 2012.

Adam Oram has written an interesting series of blog posts about the event, with some pictures. Check out the series here: https://bitly.com/bundles/praxagora/4. Thank you O'Reilly for sending Adam to help us, and chronicle the event! And most important, thank you Google for selecting our team for sponsorship. You've done KDE a great service.

Friday, September 16, 2011

New Thing: Kubuntu Documentation

For about a year I've been intending to contribute to Kubuntu Documentation, beyond the occasional update or correction of the wiki -- not that that isn't important too! But the docs which are distributed (accessed through the Help menu or F1) with all of our applications are the basic way we interact with our users all over the world. As the applications change and our settings, and suite of applications change over time, the documentation needs to be kept both current and correct. This is the role of the Documentation team. Once we're done, the docs are turned over to the Translation team, who are heroes!

Since David Wonderly (DarkwingDuck in IRC) took the leadership of the team, he's created a nice guide to contribution, at https://wiki.kubuntu.org/Kubuntu/Documentation. As I discovered during crunch time, it wasn't perfect - by the time you consult it, it will be, I'm sure!

One thing which was not stressed to me, and turned out to be important, was pulling to keep the update current. If you are working in a team, it's important to do this step frequently so that you are working on current copies of the documents.

David has documented the steps well, so I don't need to go through them here, but as in any technical process, it's important to set up your process and follow that faithfully. So always update before uploading (pushing), always fix conflicts first, and so forth.

Also, communication is important. We use a Whiteboard on Launchpad, and I discovered that I wasn't saving after claiming work items. There is no SAVE button -- just a green checkmark. Use the green checkmark! And talk to people in IRC about your intentions as well. Stepping on someone's work makes two unhappy people, and wasted worktime as well.

To sum up, getting started in Kubuntu/Ubuntu documentation involves some technical steps, such as setting up Bazaar and your SSH key, getting the Repository branch(es) you'll be working with, and keeping them up-to-date. However, they are clearly described, and help or hand-holding is available on IRC. Just follow the steps as described, and you'll have success, as I did.

The documents themselves are edited in a text editor (I use Kate, naturally), saved as usual, then committed locally, and finally pushed to Launchpad. Once uploaded, they can be checked by one of the developers and committed on Launchpad. Once you have pushed, remember to update your status on the Whiteboard, and mention it on IRC as well, if you are working in a team. #kubuntu-devel for Kubuntu, and #ubuntu-doc for everybody.

Finally, thanks for contributing to documentation! Your fellow users thank you.