5 ms·

Season of Docs

116 points by Garbage 8y ago

patrickxb 8y ago
Seems like more work to apply and mentor a technical writer than just writing the docs...
- abathur 8y ago
  Maybe. If your goal is just, like being able to say you "have documentation." Or if you are already a lucid, efficient writer. But if you aren't, or if quality and usefulness are more important than ticking a box... It's probably time well spent.
adenta 8y ago
Looks like this was rushed to publish. On my phone, some of the text overflows to the right.
- tantalor 8y ago
  Thanks for pointing that out, I sent a screenshot & message to the team working on this.
JamesBarney 8y ago
So there are lot of developers who write open source because they love writing code, feel passionately about open source, and want to increase their employment prospects. But is there a similar community of technical writers? I've only known a few but if I asked if their idea of a good time on a Saturday was banging out some technical documentation they would look at me like I'm crazy.
- abathur 8y ago
  Probably not a ton. But technical writers need resumes, too. Some of them might also be programmers. Or interested in transitioning into a programmer-writer. I pointed someone in this direction on an hn thread a few years ago. My educational background is in writing, but occupationally I'm primarily a programmer. I do some work on doc contributions, too. It's a nice way to give something, however small, back to a project I use but am not prepared to contribute code to. I think it can also build naturally to more substantive contributions. People who did not write a system but have to understand it well enough to document it are well situated to ask questions that expose design flaws, write blog posts/tutorials that help you onboard new users, triage issues, help out on any forum/list/chat, and more.
- wenc 8y ago
  I think technical writing can be fun. Not the kind of mundane technical writing where one is merely documenting APIs, but where one is explaining stuff in a tutorial-like fashion or writing about cool new features. Most people who write computer books must surely enjoy technical writing to some extent. (Would love to hear what motivates O’Reilly authors, if there are any here) For me there’s something satisfying about writing something in Sphinx and seeing the beautiful final product on readthedocs.org. I’m also the sort of person who feels a sense of satisfaction seeing my writing end up in the form of aesthetically pleasing LaTeX output. Aesthetics is unrelated to the writing process, but oddly it does seem to provide motivation for it in my experience. Also, producing a piece of writing makes me feel like I’ve made a creative contribution to the world, however small.
  - taneq 8y ago
    > Not the kind of mundane technical writing where one is merely documenting APIs, but where one is explaining stuff in a tutorial-like fashion or writing about cool new features. API documentation is one area that really, REALLY needs the latter kind of writing. There is far too much Doxygen-generated "documentation" which says things like "int foo(int power): Does 'foo' with power set to 'power' and returns the result."
    - wenc 8y ago
      I normally write API documentation as reStructuredText directly in Python docstrings which are then auto generated via Sphinx. Because I tend to write numerical algorithms, I also embed math via LaTeX tags. Sphinx converts them to MathJax which renders the math quite nicely. The final output from Sphinx is beautiful (I use the Solar theme [1] for Sphinx). As long as I keep my docstrings up to date, the API documentation generates itself and does so beautifully. I’m sure something similar exists for other languages but I would agree with you that most Doxygen docs are mechanical and devoid of the human touch (most only contain method signatures and non descriptive comments if they exist at all). They are also aesthetically unpleasant which affects their usability, which in turn dampens devs’ motivation to document their code (“why document if the final output is ugly and no one looks at it?”). I wonder if a better theme would help. [1] theme preview here https://vimalkvn.github.io/solar-theme/ https://vimalkvn.github.io/solar-theme/
- jmchuster 8y ago
  If you look around at the github pages of a lot of the successful open-source projects, you'll noticed that there's emerged this pattern of well-written readmes that give you a great overview of the intent of the project and then how to get started using it. Especially for newer projects, the lack of such a page can be a death sentence. And then such developers start to write deep technical blogs that everyone starts sharing and following. And then they start going to conferences and giving in-depth talks. All it is to say, lots of people work on open source, but if you want to become known for your work, you must become good at technical writing.
- fatnoah 8y ago
  > I've only known a few but if I asked if their idea of a good time on a Saturday was banging out some technical documentation they would look at me like I'm crazy. I fondly remember a college class where we had to produce a software product, complete with documentation, over the course of the class. Groups were randomly assigned, and one of those on my team was a technical documentation major who immediately volunteered to handle all documentation tasks. It was awesome and made appreciate having such folks around at various points in my career.
zandomatter 8y ago
Seems like it's not clear how much time involvement they're expecting? Mentors get a stipend of $500, and writers get $6000 for three months of work?
- shorts_theory 8y ago
  I believe that's only for the Google Summer of Code if you live in the US. IIRC, GSoD participants do not receive a stipend.
  - joshvm 8y ago
    You do get a stipend: https://developers.google.com/season-of-docs/docs/tech-writer-stipends https://developers.google.com/season-of-docs/docs/tech-write... It's not much, particularly as this seems to be out of the holiday season (Sep-Nov) which makes it hard for students. That said, in much of the world $2k a month (ie $24k pro rata) is a reasonable salary for writing documentation. There are worse paying graduate jobs.
tokyodude 8y ago
I'm sure one of these already exists. I kind of like writing docs or rather tutorials. I often wonder if there is a startup there, docs as a service. Hire us, we'll make your docs site and write all the docs.
- DanFeldman 8y ago
  I would absolutely pay for this. If i could walk through verbally how everything works on a large system I'm working on with a company, and then magically get some confluence docs, diagrams, autodocs, readmes, guides, this would be incredibly valuable.
- savolai 8y ago
  Isn't this what tech writers do? https://en.m.wikipedia.org/wiki/Technical_writer https://en.m.wikipedia.org/wiki/Technical_writer
  - theshrike79 8y ago
    No no, you need to add AI and blockchain in to the mix somehow.
  - taneq 8y ago
    Sure is. Where do you get one, though? Like, not full time, just for a few weeks. I think this idea has legs.
nullhorizon 8y ago
I don't think I trust the whole idea of "technical writers". Software is a complex thing. Is was recently pouring through docs of Kubernetes and Spinnaker, and with the minutia of one-off, OS specific warnings and use-cases, strange naming conventions, gotchas, and conceptual jargon, I find it really terrifying that somone who's only a "technical writer" would be writing the published documentation of such things. How do they know they're correct? Have they run the tests? Docs are hard enough to read as they are, and often, you're reading them over and over again because there's some detail that you've missed for your use case, and these are generally details possibly known only by the issue reporter or someone who actually implemented the thing. Docs aren't hard to write, and if you have to, you should just copy paste them from your comments and/or unit tests (unless you haven't written any of course). Making docs pretty and easy to write by someone else because you're too lazy too is an even bigger sin IMO. That's all I have to say about that.
- DrScump 8y ago
  How do they know they're correct? That's the whole point of having project team members (R&D, QA if a distinct organization, product management, and, ideally, Support) participate in the review process. You need someone who can write, follow (or prepare) a style guide for a consistent motif across products, and understand what the customer needs in a document. It's not their job to understand all the minutiae in a product -- that's what the broader team is for. A great tech writer is a treasure, and that person will treasure diligent reviewers. One I worked with later became a published author of historical novels.
  - abathur 8y ago
    I think this is the big thing the previous poster is missing. The technical writer isn't going to go out in the wilderness with a copy of the source, assume they understand it after reading it once, write the documentation, and hit publish. Broadly, good writing (even poetry, fiction, and creative non-fiction) has a deceptive amount of research involved. One of the subtle skills of a good writer is knowing what they don't know, and knowing how to fill the gap. Whether they're flagging things they don't understand as they go and resolving them in bulk, or regularly checking their understanding with maintainers as they encounter problems, a good technical writer isn't going to just pretend they understand.
justinclift 8y ago
If someone from the program is reading the comments here, the mentor program rules is 404: https://developers.google.com/season-of-docs/docs/program-rules https://developers.google.com/season-of-docs/docs/program-ru... That broken link is on the FAQ: https://developers.google.com/season-of-docs/docs/faq https://developers.google.com/season-of-docs/docs/faq That broken link might be intended to point to the mentor "terms": https://developers.google.com/season-of-docs/terms/mentor-terms https://developers.google.com/season-of-docs/terms/mentor-te...
- chenopis 8y ago
  Thanks! Working on a fix right now.
jackallis 8y ago
is it just me or do you all see "Mr. Burns doing the finger thing in simpsons" everytime google puts out something new?

Season of Docs

116 points by Garbage 8y ago

patrickxb 8y ago

Seems like more work to apply and mentor a technical writer than just writing the docs...

abathur 8y ago
Maybe. If your goal is just, like being able to say you "have documentation." Or if you are already a lucid, efficient writer. But if you aren't, or if quality and usefulness are more important than ticking a box... It's probably time well spent.

adenta 8y ago

Looks like this was rushed to publish. On my phone, some of the text overflows to the right.

tantalor 8y ago
Thanks for pointing that out, I sent a screenshot & message to the team working on this.

JamesBarney 8y ago

So there are lot of developers who write open source because they love writing code, feel passionately about open source, and want to increase their employment prospects. But is there a similar community of technical writers? I've only known a few but if I asked if their idea of a good time on a Saturday was banging out some technical documentation they would look at me like I'm crazy.

abathur 8y ago
Probably not a ton. But technical writers need resumes, too. Some of them might also be programmers. Or interested in transitioning into a programmer-writer. I pointed someone in this direction on an hn thread a few years ago. My educational background is in writing, but occupationally I'm primarily a programmer. I do some work on doc contributions, too. It's a nice way to give something, however small, back to a project I use but am not prepared to contribute code to. I think it can also build naturally to more substantive contributions. People who did not write a system but have to understand it well enough to document it are well situated to ask questions that expose design flaws, write blog posts/tutorials that help you onboard new users, triage issues, help out on any forum/list/chat, and more.
wenc 8y ago
I think technical writing can be fun. Not the kind of mundane technical writing where one is merely documenting APIs, but where one is explaining stuff in a tutorial-like fashion or writing about cool new features. Most people who write computer books must surely enjoy technical writing to some extent. (Would love to hear what motivates O’Reilly authors, if there are any here) For me there’s something satisfying about writing something in Sphinx and seeing the beautiful final product on readthedocs.org. I’m also the sort of person who feels a sense of satisfaction seeing my writing end up in the form of aesthetically pleasing LaTeX output. Aesthetics is unrelated to the writing process, but oddly it does seem to provide motivation for it in my experience. Also, producing a piece of writing makes me feel like I’ve made a creative contribution to the world, however small.
- taneq 8y ago
  > Not the kind of mundane technical writing where one is merely documenting APIs, but where one is explaining stuff in a tutorial-like fashion or writing about cool new features. API documentation is one area that really, REALLY needs the latter kind of writing. There is far too much Doxygen-generated "documentation" which says things like "int foo(int power): Does 'foo' with power set to 'power' and returns the result."
  - wenc 8y ago
    I normally write API documentation as reStructuredText directly in Python docstrings which are then auto generated via Sphinx. Because I tend to write numerical algorithms, I also embed math via LaTeX tags. Sphinx converts them to MathJax which renders the math quite nicely. The final output from Sphinx is beautiful (I use the Solar theme [1] for Sphinx). As long as I keep my docstrings up to date, the API documentation generates itself and does so beautifully. I’m sure something similar exists for other languages but I would agree with you that most Doxygen docs are mechanical and devoid of the human touch (most only contain method signatures and non descriptive comments if they exist at all). They are also aesthetically unpleasant which affects their usability, which in turn dampens devs’ motivation to document their code (“why document if the final output is ugly and no one looks at it?”). I wonder if a better theme would help. [1] theme preview here https://vimalkvn.github.io/solar-theme/ https://vimalkvn.github.io/solar-theme/
jmchuster 8y ago
If you look around at the github pages of a lot of the successful open-source projects, you'll noticed that there's emerged this pattern of well-written readmes that give you a great overview of the intent of the project and then how to get started using it. Especially for newer projects, the lack of such a page can be a death sentence. And then such developers start to write deep technical blogs that everyone starts sharing and following. And then they start going to conferences and giving in-depth talks. All it is to say, lots of people work on open source, but if you want to become known for your work, you must become good at technical writing.
fatnoah 8y ago
> I've only known a few but if I asked if their idea of a good time on a Saturday was banging out some technical documentation they would look at me like I'm crazy. I fondly remember a college class where we had to produce a software product, complete with documentation, over the course of the class. Groups were randomly assigned, and one of those on my team was a technical documentation major who immediately volunteered to handle all documentation tasks. It was awesome and made appreciate having such folks around at various points in my career.

zandomatter 8y ago

Seems like it's not clear how much time involvement they're expecting? Mentors get a stipend of $500, and writers get $6000 for three months of work?

shorts_theory 8y ago
I believe that's only for the Google Summer of Code if you live in the US. IIRC, GSoD participants do not receive a stipend.
- joshvm 8y ago
  You do get a stipend: https://developers.google.com/season-of-docs/docs/tech-writer-stipends https://developers.google.com/season-of-docs/docs/tech-write... It's not much, particularly as this seems to be out of the holiday season (Sep-Nov) which makes it hard for students. That said, in much of the world $2k a month (ie $24k pro rata) is a reasonable salary for writing documentation. There are worse paying graduate jobs.

tokyodude 8y ago

I'm sure one of these already exists. I kind of like writing docs or rather tutorials. I often wonder if there is a startup there, docs as a service. Hire us, we'll make your docs site and write all the docs.

DanFeldman 8y ago
I would absolutely pay for this. If i could walk through verbally how everything works on a large system I'm working on with a company, and then magically get some confluence docs, diagrams, autodocs, readmes, guides, this would be incredibly valuable.
savolai 8y ago
Isn't this what tech writers do? https://en.m.wikipedia.org/wiki/Technical_writer https://en.m.wikipedia.org/wiki/Technical_writer
- theshrike79 8y ago
  No no, you need to add AI and blockchain in to the mix somehow.
- taneq 8y ago
  Sure is. Where do you get one, though? Like, not full time, just for a few weeks. I think this idea has legs.

nullhorizon 8y ago

I don't think I trust the whole idea of "technical writers". Software is a complex thing. Is was recently pouring through docs of Kubernetes and Spinnaker, and with the minutia of one-off, OS specific warnings and use-cases, strange naming conventions, gotchas, and conceptual jargon, I find it really terrifying that somone who's only a "technical writer" would be writing the published documentation of such things. How do they know they're correct? Have they run the tests? Docs are hard enough to read as they are, and often, you're reading them over and over again because there's some detail that you've missed for your use case, and these are generally details possibly known only by the issue reporter or someone who actually implemented the thing. Docs aren't hard to write, and if you have to, you should just copy paste them from your comments and/or unit tests (unless you haven't written any of course). Making docs pretty and easy to write by someone else because you're too lazy too is an even bigger sin IMO. That's all I have to say about that.

DrScump 8y ago
How do they know they're correct? That's the whole point of having project team members (R&D, QA if a distinct organization, product management, and, ideally, Support) participate in the review process. You need someone who can write, follow (or prepare) a style guide for a consistent motif across products, and understand what the customer needs in a document. It's not their job to understand all the minutiae in a product -- that's what the broader team is for. A great tech writer is a treasure, and that person will treasure diligent reviewers. One I worked with later became a published author of historical novels.
- abathur 8y ago
  I think this is the big thing the previous poster is missing. The technical writer isn't going to go out in the wilderness with a copy of the source, assume they understand it after reading it once, write the documentation, and hit publish. Broadly, good writing (even poetry, fiction, and creative non-fiction) has a deceptive amount of research involved. One of the subtle skills of a good writer is knowing what they don't know, and knowing how to fill the gap. Whether they're flagging things they don't understand as they go and resolving them in bulk, or regularly checking their understanding with maintainers as they encounter problems, a good technical writer isn't going to just pretend they understand.

justinclift 8y ago

If someone from the program is reading the comments here, the mentor program rules is 404: https://developers.google.com/season-of-docs/docs/program-rules https://developers.google.com/season-of-docs/docs/program-ru... That broken link is on the FAQ: https://developers.google.com/season-of-docs/docs/faq https://developers.google.com/season-of-docs/docs/faq That broken link might be intended to point to the mentor "terms": https://developers.google.com/season-of-docs/terms/mentor-terms https://developers.google.com/season-of-docs/terms/mentor-te...

chenopis 8y ago
Thanks! Working on a fix right now.

jackallis 8y ago

is it just me or do you all see "Mr. Burns doing the finger thing in simpsons" everytime google puts out something new?