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: <a href="http://docs.writethedocs.org/book/" rel="nofollow">http://docs.writethedocs.org/book/</a> -- if you want somewhere to start.<p>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: <a href="http://conf.writethedocs.org/" rel="nofollow">http://conf.writethedocs.org/</a>
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.<p>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.<p>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.<p>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.
I look forward to digging into this deeper, and have a couple of questions.<p>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.<p>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: <a href="http://voiceandtone.com" rel="nofollow">http://voiceandtone.com</a> and <a href="http://www.janvwhite.org/xerox-publishing-standards" rel="nofollow">http://www.janvwhite.org/xerox-publishing-standards</a><p>Thanks!
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.<p>Highly recommend!
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..).<p>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..<p>Anyways! Looks great! I'll have to shake off the cobwebs and see how I can get involved.
I'm not sure it it's a good idea to start with a word play:<p><i>> Well, you’ve come to the write [sic] place.</i><p>I believe that most readers of that site will be non-native speakers, who may or may not get such in-language jokes.<p>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.<p>Are there any plans to extend the site in this direction?
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.