[HN Gopher] Ask HN: How to write documentation for a medium size...
___________________________________________________________________
Ask HN: How to write documentation for a medium size engineering
org?
I work for a company with ~250 engineers, and one thing that's
frustrated me is that so much knowledge is shared person-to-person
rather than being written down somewhere. A lot of times, the only
way to discover things about a new domain is to just know who
you're supposed to talk to. We have a wiki in Confluence, but it's
somewhat poorly organized and doesn't really have anyone owning its
content so it feels useless. We have one large repo and many
smaller repos that don't have great discoverability, so I don't
know that a doc directory in our code base makes sense either. Most
of the time when I'm trying to figure out how something works I'm
forced to look in Slack for people mentioning what I'm working on
(and hoping it's not locked away in a private channel). I'm
curious to hear what solutions for documentation have worked well
where others have worked? And how to 'start' an effort where I work
to better document our various domains? Edit: I'm realizing that I
need to specify: I'm not primarily interested in documenting APIs,
more things like: * Preferred way of doing X * X domain uses these
tables and works like this * This is what X feature does and here's
what it looks like Most of us work in the single large codebase,
and we don't have a good separation of responsibility between the
pieces yet (it's a work in progress) so for now I mostly want to
document what stuff exists rather than formal API documentation.
Author : docs_pls
Score : 17 points
Date : 2021-03-03 20:42 UTC (2 hours ago)
| mattchamb wrote:
| We started by building a culture of documentation within our
| team. A good place to start is with ADRs (architecture decision
| records).
|
| We also identified barriers for people to write docs on random
| topics. People thought writing docs would be onerous, so we
| explicitly encouraged low effort one liner how-tos.
|
| Getting stuff into a wiki is more important than architecting it
| properly. You can reorganize it later.
|
| You also need to refer people to the wiki to answer their
| questions.
|
| Not saying we have it sorted, but for our corner of this 400 eng
| org is making progress on useful docs
| mattchamb wrote:
| Writing docs is also important for working asynchronously so
| people were happy when writing and commenting on docs meant
| meetings started disappearing from their calendars and any
| remaining calls were more focused
| sarora27 wrote:
| Full disclosure: I'm one of the founders of a product that lets
| you create a wiki on google drive (https://kbee.app).
|
| We've been live for over 3 months and have heard first-hand about
| how hard it is to get everyone in your org to contribute to your
| wiki.
|
| In our experience/research, what we learned was that most folks
| within an organization are either:
|
| a) too intimidated by the tools they need to learn/master to
| contribute to their company wiki
|
| or
|
| b) too limited with their bandwidth to actually go through the
| process of updating your wiki using the tools you've provided.
|
| This is usually what leads to the situations you're talking
| about.
|
| Here's what we've found works in terms of creating a culture of
| documentation where everyone feels empowered to contribute to
| your wiki:
|
| 1. Use a wiki product that both the technical and non-technical
| employees feel comfortable using. This is super important. If the
| least-technically savvy teammate in your organization can not
| successfully use and contribute to your wiki, they won't use it.
| This influence will spread to other team members as well and then
| your wiki will quickly became stale and irrelevant
|
| 2. Set clear expectations around how you expect documentation to
| be formatted and presented in your wiki. This may be something a
| senior leader has to help enforce/kickoff. Give folks examples
| and scaffolding to use to create their own articles. this
| introduces a level of standardization and sets expectations for
| what is acceptable in the wiki. It also enforces a cultural
| expectation of how your organization treats documentation
|
| 3. Make referring to the documentation first a company-wide
| initiative. A great example of this is (cliche but true) how
| Amazon asks for one-pagers on a topic before the start of any
| meetings.
|
| Let me know if you have any feedback or questions. We love
| sharing what we've learned.
| [deleted]
| atmosx wrote:
| In a 250 org, I would propose to document the APIs automatically
| through swagger[^1] and use something like sphinx[^2] to get
| started for everything else. That said documentation is extra
| burden that ppl usually don't get credit for. Keep in mind that
| apart from creating the docs, the team needs to keep them up-to-
| date and that's a challenge as well. Adding "review
| documentation" in the definition of done could help.
|
| [^1]: https://swagger.io/docs/
|
| [^2]: https://www.sphinx-doc.org/en/master/
| docs_pls wrote:
| I'm realizing that I need to specify: I'm not primarily
| interested in documenting APIs, more things like:
|
| * Preferred way of doing X
|
| * X domain uses these tables and works like this
|
| * This is what X feature does and here's what it looks like
|
| Most of us work in the single large codebase, and we don't have
| a good separation of responsibility between the pieces yet
| (it's a work in progress) so for now I mostly want to document
| what stuff exists rather than formal API documentation.
| java-man wrote:
| I just have to voice an opinion that swagger is not an API
| documentation tool. It might be a helpful tool, but it does not
| produce an API specification.
|
| An API specification:
|
| - must be diff'able with any previous version
|
| - must have a version number
|
| - must specify every parameter, it's range, whether it's
| mandatory or not, list all possible values for enumerated
| types, etc.
|
| So if you use swagger, you won't be able to:
|
| - review changes needed in your part of the system before the
| code is published (even in a development environment)
|
| - analyze impact of the changes
|
| - understand the dependencies
| qbasic_forever wrote:
| If you have 250 engineers (each with a non-trivial salary and
| total comp) then you can afford hiring or contracting a few good
| technical writers. That's the solution--there's no slick
| technology, no methodology, etc. that will make hundreds of
| already busy and potentially overworked engineers churn out
| quality technical documentation. Make a case for the value of
| technical writers, take it to management, build and lead a team
| to do it...
|
| If you need some ammo, devex ('developer experience') is kind of
| a hot thing in the agile world right now. Martin Fowler has some
| good recent writings about how improvements to developer
| experience (of which technical docs are a huge part) vastly
| improve the efficiency and output of entire dev teams:
| https://martinfowler.com/articles/developer-effectiveness.ht...
|
| Spotify apparently has invested a ton of money and resources
| internally into building a first-class devex platform for their
| teams: https://backstage.io/ Watch some recent talks about it
| from Spotify folks for great feedback on how it helped their
| teams. What they've built is exactly what you describe--self-
| service, low cognitive overhead to start using and sharing tools
| across the team.
| szundi wrote:
| Until doc does not count as code, what do we expect. Not
| mentioning how most companies treat their code even. Haha.
|
| Nice to see people who are interested.
| bluGill wrote:
| Nothing works. Oh we have tried and tried. And there is a lot of
| old, out of date information scattered around. Often IT has
| changed the keys so nobody could update it anymore even if we
| knew where it still was. Then someone stumbles across it and
| makes a bad decisions.
| java-man wrote:
| 1. First of all, document the APIs in a controlled fashion
| (versions, reviews, owner, list of consumers).
|
| 2. Allow for free form notes, but with a powerful and relevant
| search. I don't think such a product exists, and Wiki/Confluence
| is a very poor choice, the search is sub-standard, in my opinion.
|
| 3. List the owners of each subsystem (and keep this list up-to-
| date).
| throwawayboise wrote:
| How long have you been with this org? If you're new, and not
| familiar with being new, this is just how it feels.
| docs_pls wrote:
| I've been with this company for years, it's way more than just
| being new unfortunately.
___________________________________________________________________
(page generated 2021-03-03 23:02 UTC)