
Write the Docs - sumnulu
http://docs.writethedocs.org
======
forsaken
Hey -- creator here. I would totally love to expand this content, as mentioned
in the comments. Let me know if you have any more questions, and would love
contributions if there are things people want to say. I have a basic outline
for some content I was thinking about turning into an ebook here:
[http://docs.writethedocs.org/book/](http://docs.writethedocs.org/book/) \--
if you want somewhere to start.

Also, note that if you're interested in this kind of thing, we have a yearly
conference in both the US and EU, and local meetups in many US cities. More
info here: [http://conf.writethedocs.org/](http://conf.writethedocs.org/)

~~~
askedrelic
I went to the first Write the Docs conference in Portland and had a great
time. It was a well organized conference with plenty of fun events and useful
knowledge. Highly recommended! Thanks again.

~~~
britta
Yes! I attended and spoke at the second conference in Portland, and it was
great.

One thing I valued from it: getting a sense of the careers of a whole crowd of
people who also do documentation as an important part of their work (and care
about it), since in a lot of technical contexts we're unusual compared to
engineers and designers. I noticed that many of us started in support, not
just me, and that it's common to wander around job titles over the decades -
from community to technical writing to engineering to product and back. I
really liked that the conference had a range of attendees and speakers in
different career stages and types of companies, so I could get a little more
of a glimpse of where I might be 10-20 years from now.

------
sixdimensional
This is great - the kind of thing product managers and technical documentation
writers should definitely know about. Thanks to the authors for providing it
and the conference.

Another cool thing about docs written this way is they are very developer
friendly but still accessible to non-developer writers - and in some
cases/organizations, getting developers to provide documentation can be
difficult. Having this be low friction between the two groups (say, non-
developers and developers) is really quite nice - both can contribute to
internal and external documentation.

I still find some folks trying to do this kind of thing in Word, and find the
markup, source control with the document conversion workflow to be many many
times more efficient.

Between generating static html for documentation sites, PDFs for
embedded/shippable/more "end user friendly" docs and more technical/plain text
formats for developers - this workflow has something for every
audience/consumer of documentation - at least for written docs.

~~~
forsaken
A lot of the experience from writing this has come from running Read the Docs:
[https://readthedocs.org/](https://readthedocs.org/) \-- which we've been
hosting OSS docs built this way for over 4 years.

We're taking these ideas and building a paid, private version for companies
that is just getting going. The goal is to take these ideas, with a product
that embodies the philosophy, and try and spread it across private companies:
[https://readthedocs.com/](https://readthedocs.com/)

Your comment that it is important and valuable is a great validation. I hope
that we're successful in being part of the solution to bringing this workflow
to the world :)

------
vitovito
I look forward to digging into this deeper, and have a couple of questions.

How much contact with related community and professional organizations have
you had, both with regards to this content and also the conference? In Austin,
we have a Content meetup, and a chapter of the Society for Technical
Communication, for example.

How much contact have you had with corporate writing departments working on
communication style guides? I'm thinking of Mailchimp's "Voice and Tone", and
the original Xerox Publishing Standards:
[http://voiceandtone.com](http://voiceandtone.com) and
[http://www.janvwhite.org/xerox-publishing-
standards](http://www.janvwhite.org/xerox-publishing-standards)

Thanks!

~~~
forsaken
We haven't had much contact with the STC. Their meetups generally cost money,
and are focused on DITA and more "old school" XML based technology. We are
trying to bring the world of devs who care about docs to the doc writers, and
make beautiful things in the process. Styled as an open source community.

We haven't had much contact with specific style guides. We have lots of people
from companies that attend. It sounds like a great topic for one of our
meetups or conference :)

------
tericho
I recently spent a good portion of 2 weeks working on a documentation strategy
for my company, so I have a lot to say on this topic. It is a daunting task
and this site definitely nails some of the pain points and offers great
starting steps.

Highly recommend!

------
jplahn
I'm definitely going to have to look into this more. One thing I _love_ is
writing, regardless of the format. While I enjoy writing code, there's
something about eloquently explaining something on paper that feels amazing. I
started writing a book on Haskell because I missed writing so much (now
whether it's any good is another matter entirely..).

This makes me think about my current classes and how there is very little
importance placed on documentation. We have to write massive javadoc comments
to appease our TAs, but rarely do we write documentation of any actual
substance. Obviously, much of this is due to the "one and done" nature of our
projects, but I digress. But when we look to get involved in open source or
"real" work at a job, we have to figure out how to write documentation that
isn't horrific. But that's a topic for another day..

Anyways! Looks great! I'll have to shake off the cobwebs and see how I can get
involved.

------
vog
I'm not sure it it's a good idea to start with a word play:

 _> Well, you’ve come to the write [sic] place._

I believe that most readers of that site will be non-native speakers, who may
or may not get such in-language jokes.

Also, what I'm missing most is not how to structure text, but a concise(!)
overview of the most important grammar rules, i.e. stuff that can't be easily
checked via dict.cc or similar sites.

Are there any plans to extend the site in this direction?

~~~
krick
> I believe that most readers of that site will be non-native speakers, who
> may or may not get such in-language jokes.

Doesn't look like a big problem to me. I'm non-native speaker myself and I got
the joke just fine, even though I didn't find it very amusing. And even if I
wouldn't, I'd just skip that sentence without worrying too much about it
(probably thinking it means "place for writing" or something like that).

~~~
vog
Don't get me wrong. I'm not a native English speaker, either. And I got that
joke, too. However, it still felt out of place there.

------
wldcordeiro
I really like ReadTheDocs and I like this encouragement to write documentation
but I think it'd be good to add more information that isn't specific to use
RST and Sphinx for non-Python developers. I personally really like RST and
Sphinx but it'd be a good way to make this a common resource.

~~~
lsiebert
I think being opinionated about which tools to use is fine, as long as it's
clear that it's an opinion. I'd add my praise to what other's have said.

One thing that strikes me is that installing python might be difficult for
windows users, especially if their PC is locked down (I have added a pull
request (edit: merged) with a link to Sphinx's instructions for windows,
though that doesn't help people with locked down PCs). It may be worth linking
to [http://rst.ninjs.org/](http://rst.ninjs.org/) which is an online
reStructed Text Editor with live preview. It is perhaps lamentable that
Windows is still a dominant desktop OS.

------
cjdrake
+1, love this initiative. Great-looking page, useful content. Looking forward
to more :).

------
computerjunkie
Great work! I will definitely be using this resource.

------
rfc791
Great base for starting documentation. Thanks!

