Categories
open source technical writing

Developer-contributed content in upstream docs

“No software spec survives first contact with the compiler.”

One of the interesting bits in the project type #1: Team=Both, Code=Up>Down, Docs=Down>Up scenario is when developers write up their feature plans in the upstream repo. Often, these show up in the /doc subdirectory.

  • Often, before coding, a developer writes up a description of the new feature they plan to code. They use this document to discuss and negotiate its implementation with other team members.
  • When the developer starts coding, code reviews replace the document as the forum of discussion.
  • Reading these feature plans and related discussions is like seeing an artist’s preliminary sketches: They represent the intention more than the result.
  • Sometimes, these preliminary docs reflect the developer’s concerns more than users’ and customers’ needs. They focus on back-end issues, celebrate accomplishments, and explain decisions.
  • These topics tend to focus more on the feature than the user story.
  • Toward the end of the project, as the feature approaches release, the developer might add user instructions to these documents.
  • Sometimes these plans describe features that didn’t make it into the software, made it in as beta or tech-preview features, or describe features that have been superseded.

In a future post, I’ll write about how to analyze and use these upstream docs to create better customer-facing docs.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.