I was speaking with Eric Redmond about this conference last week. Sounds more interesting than a conference about writing documentation might initially appear to be.
This is fantastic. This conference would not be terribly beneficial to me, but if I knew a germane conference was doing this I'd be more likely to go, just to support them.
Thanks for the kind words. We believe that coming to the conference itself will be worthwhile for many aspects. Meeting people in the community, being able to share ideas in real time, and having a shared experience of watching all the talks with other members, and having that spawn ideas and conversation.
However, we know that not everyone can make it. It's a conference about documentation, so documenting the talks just seems like a natural thing to do :) Hopefully it will be a good aid for others trying to write documentation, and serve as a resource for the good of the community in general.
We're also trying to build a resource around this kind of information on docs.writethedocs.org. It just launched today as part of this, and is half baked. However, this is the start of that doc: http://docs.writethedocs.org/en/latest/starting.html
It isn't so much about how to write documentation, but adding that section is something we want to do.
We opened up the call for speakers today with the announcement. We're planning to leave it open for 2-3 weeks. Shortly after that we'll announce the schedule.
We will also be announcing speakers as we get them confirmed throughout the following weeks. We know it's short notice, so we're trying to get the information out to people as quickly as we can.
Sounds similar to http://tom.preston-werner.com/2010/08/23/readme-driven-devel.... I've found writing my manual first to be a great way to define my project. I usually even keep a volatile roadmap, FAQ, etc that I update frequently as a way to manage tasks. Also helps make sure I don't let features creep in keeping me from shipping.
I'm the maintainer of a small but reasonably active project, and the most frequent criticism I hear of the project is that our documentation sucks. And it's true! Several people have offered to write documentation, but I've never received any pull requests. I fix up the documentation here and there, but it'll never get where it needs to be without a focused effort by someone who really cares. (And it's not that I don't, I just have a long code TODO list as well...)
A lot of these technical writers have github accounts, where presumably they contribute to open source projects in the form of documentation. Does anyone have any tips for attracting such people to a project?
I contribute to the documentation [1] for the Fluentd oss project [2].
I'm not sure how general my situation is, but in my case, a few friends were starting a company [3] and they had open sourced their log collector. Their initial team didn't have the writing skills / bandwidth to maintain great documentation [4], so they looked in their circle of friends to find a few people (including myself) with strong writing skills and a decent technical background (I work full time elsewhere).
The current workflow has developers writing the core / original documentation, which is then edited by more writing-centric people like myself (I edit heavily!).
One thing that might help, is to add the writer-friend as a committer to the project, even though he only writes documentation (this is the case for me). I think it helps with the obvious motivation issues, and also sends a message to the project at large that the project leadership deems documentation to be just as (or nearly as) important as the code itself!
[4] The CEO used to work for RedHat, which apparently treats documentation as a vital piece of their product. I remember him saying, "the documentation really is the face of a technical company".
I hear that. Riak docs used to famously suck-out-loud. It wasn't that the information was bad, it's just that no one had the time to devote to making them clean, consistent, or easy to navigate (ie. Info Arch).
Now we have some of the best NoSQL docs[1] around (clearly there's still more to do). A nice side-effect of cleaner navigation is that PRs to our repo[2] have increased dramatically.
Doc writing is a canary for how well an organization puts its money where its mouth is. Not only is documentation sometimes outright neglected, it's most often taken into an "uncanny valley" of plausibly looking like decent doc, but still sucking when actual programmers use it.
If an organization is really serious about documentation, they will not only devote resources to writing it, they will also devote serious attention to a mechanism for figuring out where it needs improvement.
Come to think of it, this would be a decent metric for figuring out which big software companies to invest in, especially if you can detect the "uncanny valley" docs efficiently. (Not only equity, but in use of their SDK/APIs.) For small software companies, there may not be enough people to write docs at first.
I was expecting some advices like: "please be short when asking questions to conferencers", "no phone calls in conf rooms" and maybe even "please go to the leisure room tif you need to play Tetris", but I got a long thing about sexual harrassment: why? Is it so that each conf is a mine field haunted with sexual predators??
24 comments
[ 3.7 ms ] story [ 68.9 ms ] threadIf my schedule permits I plan on attending.
However, we know that not everyone can make it. It's a conference about documentation, so documenting the talks just seems like a natural thing to do :) Hopefully it will be a good aid for others trying to write documentation, and serve as a resource for the good of the community in general.
It isn't so much about how to write documentation, but adding that section is something we want to do.
We also have a section currently linked to a couple of interesting projects: http://docs.writethedocs.org/en/latest/about/alternatives.ht...
We will also be announcing speakers as we get them confirmed throughout the following weeks. We know it's short notice, so we're trying to get the information out to people as quickly as we can.
The timing is a bit constrained because I am going to be hiking the Pacific Crest Trail from Mexico to Canada starting later in April: http://ericholscher.com/blog/2013/jan/10/walk-woods/
And I was planning a trip to the US in May ... this is less then perfect.
Decisions, decisions decisions.
Congrats on the book, it's a tenacious endeavor.
A lot of these technical writers have github accounts, where presumably they contribute to open source projects in the form of documentation. Does anyone have any tips for attracting such people to a project?
I'm not sure how general my situation is, but in my case, a few friends were starting a company [3] and they had open sourced their log collector. Their initial team didn't have the writing skills / bandwidth to maintain great documentation [4], so they looked in their circle of friends to find a few people (including myself) with strong writing skills and a decent technical background (I work full time elsewhere).
The current workflow has developers writing the core / original documentation, which is then edited by more writing-centric people like myself (I edit heavily!).
One thing that might help, is to add the writer-friend as a committer to the project, even though he only writes documentation (this is the case for me). I think it helps with the obvious motivation issues, and also sends a message to the project at large that the project leadership deems documentation to be just as (or nearly as) important as the code itself!
[1] https://github.com/fluent/fluentd-docs
[2] http://fluentd.org/
[3] http://www.treasure-data.com/
[4] The CEO used to work for RedHat, which apparently treats documentation as a vital piece of their product. I remember him saying, "the documentation really is the face of a technical company".
Now we have some of the best NoSQL docs[1] around (clearly there's still more to do). A nice side-effect of cleaner navigation is that PRs to our repo[2] have increased dramatically.
[1] http://docs.basho.com
[2] https://github.com/basho/basho_docs
If an organization is really serious about documentation, they will not only devote resources to writing it, they will also devote serious attention to a mechanism for figuring out where it needs improvement.
Come to think of it, this would be a decent metric for figuring out which big software companies to invest in, especially if you can detect the "uncanny valley" docs efficiently. (Not only equity, but in use of their SDK/APIs.) For small software companies, there may not be enough people to write docs at first.
I was expecting some advices like: "please be short when asking questions to conferencers", "no phone calls in conf rooms" and maybe even "please go to the leisure room tif you need to play Tetris", but I got a long thing about sexual harrassment: why? Is it so that each conf is a mine field haunted with sexual predators??