5 ms·
Product docs alongside product code
- pyronicide 5y agoI've always wanted a setup like this! It is so much easier to author docs when you can tie them directly to functionality and manage through PRs. How are you planning on managing the publishing workflow for non-devs? Marketing and docs teams tend to struggle quite a bit with git specific flows.
- englambert 5y agoWe haven't decided on that yet. We will probably use a WYSIWYG Markdown editor (recommendations welcome!) along with a Git GUI client. That may not work forever, but it should be fine in the medium-term. Note: marketing folks will probably not be editing the product docs much--the marketing site content is kept in a separate repo so we can provide a different solution there.
- personjerry 5y agoAs a PM, I thought this was about documenting the details of features and their functionality. I recently joined a startup with no documentation at all, and I spent a great deal of time documenting how everything worked. Even then, I kept being surprised by new functionality.
- polote 5y agoI agree that technical docs should be the closest to the code. But one problem of that is docs is more difficult to discover. As you need to browse the repo and docs is in the middle of source code. What I tried to do, is to use Github API to list all .md files in a repo and index them as if they were Confluence/Notion/.. docs (with tags, attributes, folders, ...). One issue, there is not a lot of granularity in the permission system of github, and the app would need to have a view right on all files of each repo, which can be an issue when you offer this app as Saas. Same this is not possible to share only one file of a repo with an external app