
A conference for all those who Write the Docs - forsaken
http://conf.writethedocs.org/
======
tych0
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?

~~~
hkmurakami
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".

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

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

~~~
pc86
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.

~~~
forsaken
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.

------
mskierkowski
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...](http://blog.factor.io/post/41716938796/docs-driven-development))

~~~
kodablah
Sounds similar to [http://tom.preston-werner.com/2010/08/23/readme-driven-
devel...](http://tom.preston-werner.com/2010/08/23/readme-driven-
development.html). 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.

------
stcredzero
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.

------
smiler
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]

~~~
aslewofmice
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>

~~~
forsaken
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...](http://docs.writethedocs.org/en/latest/about/alternatives.html#interesting-
approaches-to-documentation)

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

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

~~~
forsaken
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/>

------
tsantero
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.

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

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

------
Swizec
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.

~~~
eredmond
Plan for April :)

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

