A conference for all those who Write the Docs | Hacker News Reader

A conference for all those who Write the Docs

conf.writethedocs.org

120 pointsforsaken24 comments

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!

[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".

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.

[1] http://docs.basho.com

[2] https://github.com/basho/basho_docs

It’s too far away for me, but I’d love to see slides, recordings, streams and any other way to participate remotely.

We plan on recording all of the talks and releasing them for free.

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.

I've been looking to improve my own documentation skills so I'll definitely be a keen stream watcher!

I just submitted the first talk proposal called "Docs-driven development". Here is a brief intro: (http://blog.factor.io/post/41716938796/docs-driven-developme...)

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.

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.

Can anyone look to good guides / examples on technical writing [for those of us who are developers who have to also write docs from time to time]

Mark Phillips' beautiful docs list: https://github.com/PharkMillups/beautiful-docs

Check out https://readthedocs.org/ which is directly related to writethedocs.org. Here's a bit more instruction on how they're building up a repository of these docs: https://docs.readthedocs.org/en/latest/index.html

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 also have a section currently linked to a couple of interesting projects: http://docs.writethedocs.org/en/latest/about/alternatives.ht...

As a developer who has starting writing a lot of API documentation, this seems like an interesting conference to me. Great idea.

This is coming up fast (just over two months away) - Any idea when the speaker list/agenda might be nailed down?

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.

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/

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.

If my schedule permits I plan on attending.

I liked the idea and the design of the site, and stumbled upon its Code of Conduct. http://conf.writethedocs.org/code-of-conduct.html

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??

This kind of code of conduct is bcoming increasingly common. Here's a good explanation of why: http://jacobian.org/writing/codes-of-conduct/

I am just writing my first technical book, this is perfect!

And I was planning a trip to the US in May ... this is less then perfect.

Decisions, decisions decisions.

Plan for April :)

Congrats on the book, it's a tenacious endeavor.

Is it for O'Reilly?

Reply on news.ycombinator.com