Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Write the Docs

docs.writethedocs.org

Post reply on HN
Print view View original

11–20 of 23 posts

Re: Write the Docs

#11

Post by 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.

Re: Write the Docs

#12

Post by 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 and http://www.janvwhite.org/xerox-publishing-standards

Thanks!

Re: Write the Docs

#14

Post by forsaken »

vitovito wrote: post #12

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 st…

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 :)

Re: Write the Docs

#15

Post by Macha »

wldcordeiro wrote: post #2

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.

Markdown and RST have a common subset, and all examples given are only making use of that common subset, as I understand it.

Re: Write the Docs

#16

Post by lsiebert »

wldcordeiro wrote: post #2

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.

Re: Write the Docs

#17

Post by hereonbusiness »

forsaken wrote: post #6

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/ -- if you want somewhere to start. Also, note that if you're interested in this kind of…

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.

Re: Write the Docs

#18

Post by britta »

askedrelic wrote: post #10
forsaken wrote: post #6

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/ -- if you want somewhere to start. Also, note that if you're interested in this kind of…

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.

Re: Write the Docs

#19

Post by danielkite »

forsaken wrote: post #6

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/ -- if you want somewhere to start. Also, note that if you're interested in this kind of…

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.

Re: Write the Docs

#20

Post by 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?

Post reply on HN