
Season of Docs - Garbage
https://developers.google.com/season-of-docs/
======
JamesBarney
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.

~~~
wenc
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
> 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
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/)

~~~
abathur
Mosra has put a lot of nice work into what is roughly a Doxygen theme (I'm not
certain, but AFAIR it technically builds from the XML output and isn't a true
drop-in replacement for the default theme), m.css, which you can see in action
at [https://doc.magnum.graphics/magnum/](https://doc.magnum.graphics/magnum/)
and [https://mcss.mosra.cz/doxygen/](https://mcss.mosra.cz/doxygen/)

These demonstrate, I think, that Doxygen isn't irredeemable--but the exception
does also highlight that the ecosystem has some tendencies that aren't great
:)

------
justinclift
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-
ru...](https://developers.google.com/season-of-docs/docs/program-rules)

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-
te...](https://developers.google.com/season-of-docs/terms/mentor-terms)

~~~
chenopis
Thanks! Working on a fix right now.

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

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

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

~~~
abathur
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.

------
tokyodude
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.

~~~
savolai
Isn't this what tech writers do?
[https://en.m.wikipedia.org/wiki/Technical_writer](https://en.m.wikipedia.org/wiki/Technical_writer)

~~~
taneq
Sure is. Where do you get one, though? Like, not full time, just for a few
weeks.

I think this idea has legs.

------
zandomatter
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
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
You do get a stipend: [https://developers.google.com/season-of-docs/docs/tech-
write...](https://developers.google.com/season-of-docs/docs/tech-writer-
stipends)

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.

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

------
nullhorizon
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

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

