Write the Docs(docs.writethedocs.org)
docs.writethedocs.org
Write the Docs
http://docs.writethedocs.org
22 comments
I like the idea behind this, I also like the decision to make it a simple content driven site without distractions, but I have to say the font choice, especially for the headers is really bugging me while I'm reading.
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.
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.
Nice. Although it seems to be a lot of shower thoughts without drawing any hard lines in the sand. Exactly the kind of things I don't want in my documentation.
You will sooner or later have to have an opinion about things. If those are trivial then nothing will be taught.
You will sooner or later have to have an opinion about things. If those are trivial then nothing will be taught.
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.
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.
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.
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.
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.
A lot of the experience from writing this has come from running Read the Docs: 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/
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 :)
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 :)
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 and http://www.janvwhite.org/xerox-publishing-standards
Thanks!
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 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 :)
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 :)
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!
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..).
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.
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.
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?
> 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 can’t think of any grammar rules that are more applicable to documentation than to other writing. Thus, I think giving an overview of grammar rules would be out-of-scope for this site, and shouldn’t be added. However, it might be in scope for this site to have an appendix with a list of links about writing in general, and such a grammar site would deserve a spot.
> 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?
> 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?
> 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).
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).
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.
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.
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/ which is an online reStructed Text Editor with live preview. It is perhaps lamentable that Windows is still a dominant desktop OS.
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.
Markdown and RST have a common subset, and all examples given are only making use of that common subset, as I understand it.
The beginners guide is explicitly using general markup, instead of Sphinx specifically. Almost none of the content on the site is actually Sphinx-specific..
+1, love this initiative. Great-looking page, useful content. Looking forward to more :).
Great work! I will definitely be using this resource.
Great base for starting documentation. Thanks!
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/