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/
I don't usually care much about things like this but even just removing Hagin Caps Medium from the headers makes it much easier on the eyes in my opinion.
You will sooner or later have to have an opinion about things. If those are trivial then nothing will be taught.
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.
> 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?
> I believe that most readers of that site will be non-native speakers
I don’t see why this site would get a higher proportion of non-native speakers than any other site. Learning to understand a language and learning to write well in it are mostly separate things, and I think native speakers will understand that, so they won’t avoid using this site just because it’s about writing in English. Or are you saying that there are more non-native-speaker users in general who browse English programming sites than native-speaker users?
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).
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/ which is an online reStructed Text Editor with live preview. It is perhaps lamentable that Windows is still a dominant desktop OS.
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.
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/
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 :)
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 and http://www.janvwhite.org/xerox-publishing-standards
Thanks!
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 :)
Highly recommend!
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.
